@cohortapp/agent-sdk 2.3.0

package/scripts/slack-events-server.mjs

@@ -0,0 +1,1045 @@
+#!/usr/bin/env node
+/**
+ * Slack Events API Server — Real-Time Event Receiver
+ *
+ * Receives real-time events from Slack via the bot's Event Subscriptions.
+ * Writes inbound events to state/inbox/slack/ in YAML format (matching poller output).
+ * Creates priority trigger files for CEO DMs.
+ *
+ * This replaces polling — Slack pushes events to us instantly.
+ *
+ * Events handled:
+ *   - message (DM, channel messages, thread replies — all channel types)
+ *   - app_mention (the agent @mentioned)
+ *   - reaction_added (emoji reactions)
+ *
+ * Deduplication:
+ *   - Tracks event_id in state/locks/slack-events/ to prevent duplicate processing
+ *   - Also deduplicates against the poller's tracker in state/slack-thread-tracker/
+ *
+ * Usage: node scripts/slack-events-server.mjs
+ * Requires: SLACK_BOT_TOKEN (or SLACK_TOKEN), SLACK_SIGNING_SECRET in .env
+ * Port: 3100 (configurable via SLACK_EVENTS_PORT)
+ */
+
+import http from "node:http";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, "..");
+
+// ── Singleton guard — prevent duplicate instances ────────────────────────────
+try {
+  process.env.AGENT_ROOT = process.env.AGENT_ROOT || ROOT;
+  const { acquireLock } = await import("../lib/singleton.js");
+  if (!acquireLock("slack-events")) {
+    console.log("[INIT] Slack events server already running — exiting");
+    process.exit(0);
+  }
+} catch { /* maestro not available — skip guard */ }
+
+// ── Load environment ──────────────────────────────────────────────────────────
+
+const envPath = path.join(ROOT, ".env");
+if (fs.existsSync(envPath)) {
+  const envContent = fs.readFileSync(envPath, "utf-8");
+  for (const line of envContent.split("\n")) {
+    const match = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+    if (match) {
+      let val = match[2].trim();
+      // Strip surrounding quotes
+      if (
+        (val.startsWith('"') && val.endsWith('"')) ||
+        (val.startsWith("'") && val.endsWith("'"))
+      ) {
+        val = val.slice(1, -1);
+      }
+      process.env[match[1]] = val;
+    }
+  }
+}
+
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+const PORT = parseInt(process.env.SLACK_EVENTS_PORT || "3100", 10);
+const SIGNING_SECRET = process.env.SLACK_SIGNING_SECRET || "";
+
+// Fail-closed: this endpoint accepts inbound Slack events and injects them into
+// the inbox. Without the signing secret it cannot verify requests, which would
+// let anyone on the internet forge inbound messages. Refuse to start rather
+// than degrade to "skip verification". (Mirrors scripts/cloud-relay/index.mjs.)
+if (!SIGNING_SECRET) {
+  console.error("FATAL: SLACK_SIGNING_SECRET env var is required (refusing to start fail-open)");
+  process.exit(78); // EX_CONFIG
+}
+
+const INBOX_DIR = path.join(ROOT, "state/inbox/slack");
+const DEDUP_DIR = path.join(ROOT, "state/locks/slack-events");
+const POLLER_TRACKER_DIR = path.join(ROOT, "state/slack-thread-tracker");
+const TRIGGER_DIR = path.join(ROOT, "state/triggers/priority");
+const LOG_DIR = path.join(ROOT, "logs/polling");
+
+// Load the running agent's identity (canonical SOT) so we can filter
+// self-messages and resolve the principal's user ID without hardcoding.
+let _agent = null;
+function loadAgent() {
+  if (_agent) return _agent;
+  try {
+    _agent = JSON.parse(fs.readFileSync(path.join(ROOT, "config/agent.json"), "utf-8"));
+  } catch {
+    _agent = { firstName: "Agent", slackMemberId: "", fullName: "Agent", principal: {} };
+  }
+  return _agent;
+}
+
+const AGENT_USER_ID = loadAgent().slackMemberId || "";
+const PRINCIPAL_USER_ID = loadAgent().principal?.slackMemberId || "";
+// DM channel between the principal and the agent — resolved at runtime from
+// Slack API on first DM event. The hardcoded MEHRAN_DM_CHANNEL constant was
+// removed; the server detects DM channels via the Slack channel ID prefix
+// (channels starting with "D" are IM channels).
+
+// Known users for name/privilege resolution — built from agent.json so each
+// agent's principal gets `privilege: ceo` and the agent itself gets `system`.
+const KNOWN_USERS = (() => {
+  const a = loadAgent();
+  const map = {};
+  if (a.principal?.slackMemberId) {
+    map[a.principal.slackMemberId] = {
+      name: (a.principal.fullName || "").toLowerCase().replace(/\s+/g, "-"),
+      privilege: "ceo",
+    };
+  }
+  if (a.slackMemberId) {
+    map[a.slackMemberId] = {
+      name: (a.fullName || "").toLowerCase().replace(/\s+/g, "-"),
+      privilege: "system",
+    };
+  }
+  return map;
+})();
+
+// Monitored channels (matches poller/slack-poller.mjs)
+const CHANNEL_INFO = {
+  C0ARASMQE1W: { name: "ceo-office", priority: "critical" },
+  C099NT6NKK7: { name: "engineering", priority: "high" },
+  C097N5R8HUJ: { name: "all-company", priority: "high" },
+  C09916RV399: { name: "engineering-platform", priority: "high" },
+  C0AQEGXKYT0: { name: "regulatory-remediation", priority: "high" },
+  C0AQGK5TLNN: { name: "strategic-initiative", priority: "high" },
+  C0AQL7QL2G4: { name: "legal-compliance", priority: "high" },
+  C0996CRGF1S: { name: "company-app", priority: "normal" },
+  C0992UF9469: { name: "platform", priority: "normal" },
+  C0ARAU328JU: { name: "general", priority: "normal" },
+  C09CTAFUB09: { name: "product", priority: "normal" },
+};
+
+const ATTACHMENTS_DIR = path.join(ROOT, "state/inbox/attachments");
+
+// Ensure attachments directory exists
+fs.mkdirSync(ATTACHMENTS_DIR, { recursive: true });
+
+/**
+ * Extract attachment metadata from Slack event files array.
+ * Also attempts to download files for local access by Claude Code sessions.
+ */
+function extractAttachments(files) {
+  if (!files || !Array.isArray(files) || files.length === 0) return [];
+  const token = process.env.SLACK_BOT_TOKEN || process.env.SLACK_TOKEN || "";
+  return files.map((f) => {
+    const att = {
+      id: f.id || "",
+      name: f.name || "unnamed",
+      mimetype: f.mimetype || f.filetype || "unknown",
+      size: f.size || 0,
+      url_private: f.url_private || "",
+      local_path: null,
+    };
+    // Attempt synchronous-style download via fetch (non-blocking best-effort)
+    if (token && (f.url_private_download || f.url_private)) {
+      const safeId = (f.id || "unknown").replace(/[^a-zA-Z0-9_-]/g, "");
+      const safeName = (f.name || "file").replace(/[^a-zA-Z0-9._-]/g, "_");
+      const localPath = path.join(ATTACHMENTS_DIR, `${safeId}-${safeName}`);
+      att.local_path = localPath; // Set optimistically; download happens async
+      // Fire-and-forget async download
+      downloadAttachment(f.url_private_download || f.url_private, localPath, token);
+    }
+    return att;
+  });
+}
+
+/**
+ * Download a Slack attachment to local storage (async, fire-and-forget).
+ */
+async function downloadAttachment(url, localPath, token) {
+  try {
+    if (fs.existsSync(localPath)) return; // Already downloaded
+    const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
+    if (!res.ok) {
+      log("WARN", `Attachment download failed: HTTP ${res.status}`, { url });
+      return;
+    }
+    const buffer = Buffer.from(await res.arrayBuffer());
+    fs.writeFileSync(localPath, buffer);
+    log("INFO", `Attachment downloaded: ${path.basename(localPath)}`, { size: buffer.length });
+  } catch (err) {
+    log("WARN", `Attachment download error: ${err.message}`, { url });
+  }
+}
+
+// ── Edit Deduplication ───────────────────────────────────────────────────────
+
+/**
+ * Calculate word-level similarity between two strings (Jaccard-like).
+ * Returns 0.0 (completely different) to 1.0 (identical).
+ * Used to distinguish typo fixes from material edits.
+ */
+function wordSimilarity(a, b) {
+  if (a === b) return 1.0;
+  if (!a && !b) return 1.0;
+  if (!a || !b) return 0.0;
+
+  const wordsA = a.toLowerCase().split(/\s+/).filter(Boolean);
+  const wordsB = b.toLowerCase().split(/\s+/).filter(Boolean);
+
+  if (wordsA.length === 0 && wordsB.length === 0) return 1.0;
+  if (wordsA.length === 0 || wordsB.length === 0) return 0.0;
+
+  const setA = new Set(wordsA);
+  const setB = new Set(wordsB);
+  const intersection = new Set([...setA].filter((w) => setB.has(w)));
+  const union = new Set([...setA, ...setB]);
+
+  return intersection.size / union.size;
+}
+
+/**
+ * Mark an existing inbox item as superseded by a message edit.
+ * Renames the YAML file with a .superseded suffix so the inbox processor
+ * skips it and processes only the new version.
+ */
+function supersedeInboxItem(channelId, messageTs) {
+  try {
+    const tsFormatted = messageTs.replace(".", "-");
+    const files = fs.readdirSync(INBOX_DIR);
+    for (const file of files) {
+      if (file.includes(tsFormatted) && file.endsWith(".yaml") && !file.endsWith(".superseded")) {
+        const oldPath = path.join(INBOX_DIR, file);
+        const newPath = path.join(INBOX_DIR, file + ".superseded");
+        fs.renameSync(oldPath, newPath);
+        log("INFO", `Superseded inbox item: ${file}`, { channel: channelId, ts: messageTs });
+      }
+    }
+  } catch (err) {
+    log("WARN", `Failed to supersede inbox item: ${err.message}`, { channel: channelId, ts: messageTs });
+  }
+}
+
+// Dedup cache: keep event_ids in memory for fast lookup (last 10,000)
+const eventIdCache = new Set();
+const MAX_CACHE_SIZE = 10000;
+
+// Stats for health endpoint
+const stats = {
+  started_at: new Date().toISOString(),
+  events_received: 0,
+  events_processed: 0,
+  events_deduplicated: 0,
+  events_skipped_bot: 0,
+  last_event_at: null,
+  errors: 0,
+};
+
+// ── Ensure directories exist ──────────────────────────────────────────────────
+
+for (const dir of [INBOX_DIR, DEDUP_DIR, TRIGGER_DIR, LOG_DIR]) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function resolveName(userId) {
+  return KNOWN_USERS[userId]?.name || userId;
+}
+
+function resolvePrivilege(userId) {
+  return KNOWN_USERS[userId]?.privilege || "unknown";
+}
+
+function resolveChannelName(channelId, channelType) {
+  if (CHANNEL_INFO[channelId]) {
+    return CHANNEL_INFO[channelId].name;
+  }
+  if (channelType === "im") {
+    return `dm/${channelId}`;
+  }
+  return channelId;
+}
+
+/**
+ * Verify Slack request signature (v0 HMAC-SHA256)
+ * Returns true if valid, false if invalid.
+ * Fails closed: a missing secret must never degrade to "skip verification".
+ * (The boot guard already refuses to start without it; this is defence in depth.)
+ */
+function verifySlackSignature(timestamp, body, signature) {
+  if (!SIGNING_SECRET) return false;
+
+  // Reject requests older than 5 minutes (replay protection)
+  const now = Math.floor(Date.now() / 1000);
+  if (Math.abs(now - parseInt(timestamp, 10)) > 300) {
+    log("WARN", "Request timestamp too old, possible replay attack");
+    return false;
+  }
+
+  const sigBasestring = `v0:${timestamp}:${body}`;
+  const mySignature =
+    "v0=" +
+    crypto
+      .createHmac("sha256", SIGNING_SECRET)
+      .update(sigBasestring, "utf8")
+      .digest("hex");
+
+  try {
+    return crypto.timingSafeEqual(
+      Buffer.from(mySignature),
+      Buffer.from(signature || ""),
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if an event has already been processed.
+ * Uses both in-memory cache and filesystem dedup directory.
+ */
+function isDuplicate(eventId) {
+  if (!eventId) return false;
+
+  // Check memory cache first
+  if (eventIdCache.has(eventId)) return true;
+
+  // Check filesystem
+  const dedupFile = path.join(DEDUP_DIR, eventId);
+  if (fs.existsSync(dedupFile)) {
+    eventIdCache.add(eventId);
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Mark an event as processed for deduplication.
+ */
+function markProcessed(eventId) {
+  if (!eventId) return;
+
+  // Add to memory cache
+  eventIdCache.add(eventId);
+
+  // Evict oldest entries if cache is too large
+  if (eventIdCache.size > MAX_CACHE_SIZE) {
+    const iterator = eventIdCache.values();
+    for (let i = 0; i < 1000; i++) {
+      eventIdCache.delete(iterator.next().value);
+    }
+  }
+
+  // Write to filesystem
+  try {
+    fs.writeFileSync(path.join(DEDUP_DIR, eventId), String(Date.now()));
+  } catch (err) {
+    log("ERROR", `Failed to write dedup file for ${eventId}: ${err.message}`);
+  }
+}
+
+/**
+ * Also mark in the poller's tracker so the comms-monitor.sh doesn't re-process.
+ */
+function markInPollerTracker(messageTs) {
+  if (!messageTs) return;
+  try {
+    const trackerFile = path.join(POLLER_TRACKER_DIR, messageTs);
+    if (!fs.existsSync(trackerFile)) {
+      fs.mkdirSync(POLLER_TRACKER_DIR, { recursive: true });
+      fs.writeFileSync(trackerFile, messageTs);
+    }
+  } catch {
+    // Non-critical — poller will just reprocess
+  }
+}
+
+/**
+ * Write structured log entry
+ */
+function log(level, message, data = {}) {
+  const entry = {
+    timestamp: new Date().toISOString(),
+    service: "slack-events-server",
+    level,
+    message,
+    ...data,
+  };
+  const line = JSON.stringify(entry);
+  console.log(`[${level}] ${message}`);
+
+  // Append to daily log file
+  try {
+    const today = new Date().toISOString().split("T")[0];
+    const logFile = path.join(LOG_DIR, `${today}-slack-events.jsonl`);
+    fs.appendFileSync(logFile, line + "\n");
+  } catch {
+    // Logging failure should not break event processing
+  }
+}
+
+// ── Inbox Writers ─────────────────────────────────────────────────────────────
+
+/**
+ * Write an inbox item in YAML format — matching the poller's output exactly.
+ * This ensures the inbox processor handles events from both sources identically.
+ */
+function writeInboxYaml(item) {
+  const ts = (item.timestamp || new Date().toISOString()).replace(/[:.]/g, "-");
+  const filename = `${ts}-${item.id}.yaml`;
+  const filepath = path.join(INBOX_DIR, filename);
+
+  const content = (item.content || "").replace(/\n/g, "\n  ");
+  let yaml = `id: "${item.id}"
+service: "${item.service}"
+channel: "${item.channel}"
+sender: "${item.sender}"
+sender_privilege: "${item.sender_privilege}"
+timestamp: "${item.timestamp}"
+subject: "${item.subject || ""}"
+content: |
+  ${content}
+thread_id: "${item.thread_id || ""}"
+is_reply: ${item.is_reply || false}
+is_voice_transcript: false
+priority_signals:
+  from_ceo: ${item.priority_signals?.from_ceo || false}
+  tagged_urgent: ${item.priority_signals?.tagged_urgent || false}
+  contains_deadline: ${item.priority_signals?.contains_deadline || false}
+  mentions_agent: ${item.priority_signals?.mentions_agent || false}
+raw_ref: "${item.raw_ref || ""}"
+source: "events-api"
+`;
+
+  // Add attachments if present
+  if (item.attachments && item.attachments.length > 0) {
+    yaml += `attachments:\n`;
+    for (const att of item.attachments) {
+      yaml += `  - id: "${att.id}"\n`;
+      yaml += `    name: "${att.name}"\n`;
+      yaml += `    mimetype: "${att.mimetype}"\n`;
+      yaml += `    size: ${att.size}\n`;
+      if (att.local_path) {
+        yaml += `    local_path: "${att.local_path}"\n`;
+      }
+      if (att.url_private) {
+        yaml += `    url_private: "${att.url_private}"\n`;
+      }
+    }
+  }
+
+  fs.writeFileSync(filepath, yaml);
+  log("INFO", `Inbox item written: ${filename}`, {
+    event_type: item._eventType,
+    sender: item.sender,
+    channel: item.channel,
+  });
+  return filepath;
+}
+
+/**
+ * Write a priority trigger file for CEO DMs and urgent items.
+ * This triggers immediate session pickup by the inbox processor.
+ */
+function writePriorityTrigger(event, reason) {
+  const ts = Date.now();
+  const triggerFile = path.join(TRIGGER_DIR, `ceo-dm-${ts}.yaml`);
+  const content = (event.text || "").replace(/\n/g, "\n  ");
+  const triggerContent = `type: priority_trigger
+reason: "${reason}"
+source: "slack:${event.channel}:${event.ts}"
+sender: "${resolveName(event.user)}"
+channel: "${resolveChannelName(event.channel, event.channel_type)}"
+timestamp: "${new Date().toISOString()}"
+detected_by: slack-events-server
+content: |
+  ${content}
+`;
+  fs.writeFileSync(triggerFile, triggerContent);
+  log("INFO", `Priority trigger written: ceo-dm-${ts}.yaml`, { reason });
+  return triggerFile;
+}
+
+// ── Event Handlers ────────────────────────────────────────────────────────────
+
+/**
+ * Process a message event (DM, channel, thread reply — any channel type).
+ */
+function handleMessageEvent(event) {
+  const userId = event.user || "";
+  // Skip the agent's own messages — defensive check (outer dispatch also filters,
+  // but message_changed normalization can bypass it)
+  if (userId === AGENT_USER_ID) return;
+
+  const msgText = event.text || "";
+  const channelId = event.channel || "";
+  const channelType = event.channel_type || "";
+  const isThread = !!event.thread_ts && event.thread_ts !== event.ts;
+  const isDM = channelType === "im";
+  const isPrincipal = userId === PRINCIPAL_USER_ID;
+  // The principal's DM channel is whichever IM channel they happen to use to
+  // contact the agent — Slack assigns DM channel IDs dynamically. Detect
+  // principal-DM context from `isPrincipal && isDM` rather than a hardcode.
+  const isPrincipalDmChannel = isPrincipal && isDM;
+  const agentFirstName = (loadAgent().firstName || "").toLowerCase();
+  const mentionsAgent =
+    (agentFirstName && msgText.toLowerCase().includes(agentFirstName)) ||
+    (AGENT_USER_ID && msgText.includes(`<@${AGENT_USER_ID}>`));
+  const isUrgent = /\b(urgent|emergency|asap|blocker|critical)\b/i.test(
+    msgText,
+  );
+
+  // Determine channel name and subject
+  let channelName, subject;
+  if (isDM) {
+    channelName = `dm/${resolveName(userId)}`;
+    subject = `DM from ${resolveName(userId)}`;
+  } else {
+    channelName = resolveChannelName(channelId, channelType);
+    subject = `#${channelName}`;
+    if (isThread) {
+      subject += " (thread reply)";
+    }
+  }
+
+  log("INFO", `Message event`, {
+    from: resolveName(userId),
+    channel: channelName,
+    isDM,
+    isThread,
+    isPrincipal,
+    mentionsAgent,
+    isUrgent,
+  });
+
+  // Extract attachment metadata from event.files (Slack Events API includes these)
+  const attachments = extractAttachments(event.files);
+
+  // Build inbox item matching poller format
+  const msgTs = event.ts || "";
+  const inboxItem = {
+    id: msgTs.replace(".", "-"),
+    service: "slack",
+    channel: channelName,
+    sender: resolveName(userId),
+    sender_privilege: resolvePrivilege(userId),
+    timestamp: new Date(parseFloat(msgTs) * 1000).toISOString(),
+    subject,
+    content: msgText,
+    thread_id: event.thread_ts || "",
+    is_reply: isThread,
+    attachments: attachments.length > 0 ? attachments : undefined,
+    priority_signals: {
+      from_ceo: isPrincipal,
+      tagged_urgent: isUrgent,
+      contains_deadline: false,
+      mentions_agent: mentionsAgent || isDM,
+    },
+    raw_ref: `slack:${channelId}:${msgTs}`,
+    _eventType: isThread ? "thread_reply" : isDM ? "dm" : "channel_message",
+  };
+
+  writeInboxYaml(inboxItem);
+
+  // Mark in poller tracker to prevent comms-monitor.sh from re-processing
+  markInPollerTracker(msgTs);
+
+  // Write priority trigger for CEO DMs, @mentions, and urgent messages
+  if (isPrincipal && (isDM || isPrincipalDmChannel)) {
+    writePriorityTrigger(event, "CEO DM via Events API");
+  } else if (isPrincipal && !isDM) {
+    writePriorityTrigger(event, "CEO channel message via Events API");
+  } else if (mentionsAgent) {
+    writePriorityTrigger(event, "Agent @mentioned via Events API");
+  } else if (isUrgent) {
+    writePriorityTrigger(event, "Urgent message via Events API");
+  }
+}
+
+/**
+ * Process an app_mention event (@-mention of the running agent).
+ */
+function handleMentionEvent(event) {
+  const msgText = event.text || "";
+  const userId = event.user || "";
+  const channelId = event.channel || "";
+  const isPrincipal = userId === PRINCIPAL_USER_ID;
+  const isUrgent = /\b(urgent|emergency|asap|blocker|critical)\b/i.test(
+    msgText,
+  );
+  const channelName = resolveChannelName(channelId, "channel");
+  const msgTs = event.ts || "";
+
+  log("INFO", `App mention event`, {
+    from: resolveName(userId),
+    channel: channelName,
+  });
+
+  const inboxItem = {
+    id: msgTs.replace(".", "-"),
+    service: "slack",
+    channel: channelName,
+    sender: resolveName(userId),
+    sender_privilege: resolvePrivilege(userId),
+    timestamp: new Date(parseFloat(msgTs) * 1000).toISOString(),
+    subject: `@${loadAgent().firstName || "Agent"} in #${channelName}`,
+    content: msgText,
+    thread_id: event.thread_ts || "",
+    is_reply: !!event.thread_ts && event.thread_ts !== event.ts,
+    priority_signals: {
+      from_ceo: isPrincipal,
+      tagged_urgent: isUrgent,
+      contains_deadline: false,
+      mentions_agent: true,
+    },
+    raw_ref: `slack:${channelId}:${msgTs}`,
+    _eventType: "mention",
+  };
+
+  writeInboxYaml(inboxItem);
+  markInPollerTracker(msgTs);
+
+  // Mentions always get a priority trigger
+  writePriorityTrigger(
+    event,
+    isPrincipal
+      ? "CEO @mention via Events API"
+      : "Agent @mentioned via Events API",
+  );
+}
+
+/**
+ * Process a reaction_added event.
+ */
+function handleReactionEvent(event) {
+  const userId = event.user || "";
+  const reaction = event.reaction || "";
+  const itemTs = event.item?.ts || "";
+  const itemChannel = event.item?.channel || "";
+  const isPrincipal = userId === PRINCIPAL_USER_ID;
+  const channelName = resolveChannelName(itemChannel, "channel");
+
+  log("INFO", `Reaction event: :${reaction}: from ${resolveName(userId)}`, {
+    channel: channelName,
+    on_message: itemTs,
+  });
+
+  // Write reaction as inbox item — reactions from CEO are priority signals
+  const inboxItem = {
+    id: `${itemTs}-${reaction}-${userId}`.replace(/\./g, "-"),
+    service: "slack",
+    channel: channelName,
+    sender: resolveName(userId),
+    sender_privilege: resolvePrivilege(userId),
+    timestamp: new Date().toISOString(),
+    subject: `:${reaction}: on message in #${channelName}`,
+    content: `Reaction :${reaction}: added by ${resolveName(userId)} on message ${itemTs}`,
+    thread_id: "",
+    is_reply: false,
+    priority_signals: {
+      from_ceo: isPrincipal,
+      tagged_urgent: false,
+      contains_deadline: false,
+      mentions_agent: false,
+    },
+    raw_ref: `slack:${itemChannel}:${itemTs}:reaction:${reaction}`,
+    _eventType: "reaction",
+  };
+
+  writeInboxYaml(inboxItem);
+}
+
+// ── Huddle Event Handler ──────────────────────────────────────────────────────
+
+/**
+ * Handle user_huddle_changed events — forwarded to the huddle server
+ * for real-time huddle detection and auto-join.
+ */
+function handleHuddleEvent(event) {
+  const userId = event.user || "";
+  const huddleState = event.huddle_state || "";
+
+  // Don't react to the agent's own huddle changes
+  if (userId === AGENT_USER_ID) return;
+
+  const userName = resolveName(userId);
+
+  log("INFO", `Huddle event: ${userName} → ${huddleState}`, {
+    user: userId,
+    huddle_state: huddleState,
+  });
+
+  // Forward to huddle server's event listener
+  const huddleServerUrl = `http://127.0.0.1:${process.env.HUDDLE_EVENTS_PORT || 3200}/huddle-event`;
+
+  const payload = JSON.stringify({
+    user: userId,
+    user_name: userName,
+    huddle_state: huddleState,
+    // user_huddle_changed doesn't include channel info directly,
+    // but we can derive it from context if available
+    channel: event.channel || null,
+    channel_type: event.channel_type || null,
+    timestamp: new Date().toISOString(),
+  });
+
+  // Fire-and-forget POST to huddle server
+  fetch(huddleServerUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: payload,
+  }).catch((err) => {
+    // Huddle server may not be running — that's fine
+    log("DEBUG", `Huddle server unreachable: ${err.message}`);
+  });
+}
+
+// ── Main Event Router ─────────────────────────────────────────────────────────
+
+/**
+ * Route an incoming Slack event to the appropriate handler.
+ */
+function handleEvent(payload) {
+  const event = payload.event;
+  if (!event) return;
+
+  const eventId = payload.event_id;
+
+  // Deduplication check
+  if (isDuplicate(eventId)) {
+    stats.events_deduplicated++;
+    log("DEBUG", `Duplicate event skipped: ${eventId}`);
+    return;
+  }
+
+  stats.events_received++;
+  stats.last_event_at = new Date().toISOString();
+
+  // Skip bot messages (including the agent's own messages)
+  if (event.bot_id || event.subtype === "bot_message") {
+    stats.events_skipped_bot++;
+    log("DEBUG", `Bot message skipped`, {
+      bot_id: event.bot_id,
+      subtype: event.subtype,
+    });
+    markProcessed(eventId);
+    return;
+  }
+
+  // Skip the agent's own messages
+  if (event.user === AGENT_USER_ID) {
+    stats.events_skipped_bot++;
+    markProcessed(eventId);
+    return;
+  }
+
+  // Handle message_changed: Slack sends both old and new text.
+  // Compare to determine if the edit is material (rewrite) or immaterial (typo fix).
+  if (event.subtype === "message_changed" && event.message) {
+    const oldText = event.previous_message?.text || "";
+    const newText = event.message.text || "";
+    const similarity = wordSimilarity(oldText, newText);
+
+    if (similarity >= 0.90) {
+      // Immaterial edit (typo fix, formatting) — skip reprocessing
+      stats.events_deduplicated++;
+      log("INFO", `Immaterial edit skipped (${(similarity * 100).toFixed(0)}% similar)`, {
+        channel: event.channel,
+        ts: event.message.ts,
+      });
+      markProcessed(eventId);
+      return;
+    }
+
+    // Material edit — supersede the old inbox item and process the new version
+    log("INFO", `Material edit detected (${(similarity * 100).toFixed(0)}% similar)`, {
+      channel: event.channel,
+      ts: event.message.ts,
+    });
+    supersedeInboxItem(event.channel, event.message.ts);
+
+    // Normalize event shape for the message handler
+    event.text = newText;
+    event.user = event.message.user || event.user;
+    event.ts = event.message.ts || event.ts;
+    event.thread_ts = event.message.thread_ts || event.thread_ts;
+    event.files = event.message.files || event.files;
+    event._is_edit = true;
+
+    // Re-check after normalization: the original event.user for
+    // message_changed is often empty/system; the real author is in
+    // event.message.user. Without this, the agent's own edited messages
+    // bypass the earlier AGENT_USER_ID filter and trigger self-replies.
+    if (event.user === AGENT_USER_ID) {
+      stats.events_skipped_bot++;
+      markProcessed(eventId);
+      return;
+    }
+    // Fall through to message handler with updated content
+  }
+
+  // Skip message subtypes that are not actual user messages
+  // (channel_join, channel_leave, channel_topic, etc.)
+  const ignoredSubtypes = new Set([
+    "channel_join",
+    "channel_leave",
+    "channel_topic",
+    "channel_purpose",
+    "channel_name",
+    "channel_archive",
+    "channel_unarchive",
+    "bot_add",
+    "bot_remove",
+    "pinned_item",
+    "unpinned_item",
+  ]);
+  if (event.subtype && ignoredSubtypes.has(event.subtype)) {
+    markProcessed(eventId);
+    return;
+  }
+
+  // Route by event type
+  try {
+    switch (event.type) {
+      case "message":
+        handleMessageEvent(event);
+        break;
+      case "app_mention":
+        handleMentionEvent(event);
+        break;
+      case "reaction_added":
+        handleReactionEvent(event);
+        break;
+      case "user_huddle_changed":
+        handleHuddleEvent(event);
+        break;
+      default:
+        log("WARN", `Unhandled event type: ${event.type}`);
+    }
+    stats.events_processed++;
+  } catch (err) {
+    stats.errors++;
+    log("ERROR", `Failed to process event: ${err.message}`, {
+      event_type: event.type,
+      event_id: eventId,
+      stack: err.stack,
+    });
+  }
+
+  // Mark as processed after handling
+  markProcessed(eventId);
+}
+
+// ── Dedup Cleanup (runs hourly) ───────────────────────────────────────────────
+
+/**
+ * Clean up old dedup files (older than 24 hours) to prevent disk bloat.
+ */
+function cleanupDedupFiles() {
+  try {
+    const files = fs.readdirSync(DEDUP_DIR);
+    const cutoff = Date.now() - 24 * 60 * 60 * 1000; // 24 hours ago
+    let cleaned = 0;
+
+    for (const file of files) {
+      const filepath = path.join(DEDUP_DIR, file);
+      try {
+        const content = fs.readFileSync(filepath, "utf-8").trim();
+        const ts = parseInt(content, 10);
+        if (!isNaN(ts) && ts < cutoff) {
+          fs.unlinkSync(filepath);
+          cleaned++;
+        }
+      } catch {
+        // If we can't read it, check mtime instead
+        try {
+          const stat = fs.statSync(filepath);
+          if (stat.mtimeMs < cutoff) {
+            fs.unlinkSync(filepath);
+            cleaned++;
+          }
+        } catch {
+          // Skip
+        }
+      }
+    }
+
+    if (cleaned > 0) {
+      log("INFO", `Dedup cleanup: removed ${cleaned} old entries`);
+    }
+  } catch (err) {
+    log("ERROR", `Dedup cleanup failed: ${err.message}`);
+  }
+}
+
+// Run cleanup every hour
+setInterval(cleanupDedupFiles, 60 * 60 * 1000);
+
+// ── HTTP Server ───────────────────────────────────────────────────────────────
+
+const server = http.createServer((req, res) => {
+  // Health check endpoint
+  if (req.method === "GET" && req.url === "/health") {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(
+      JSON.stringify({
+        status: "ok",
+        service: "slack-events-server",
+        port: PORT,
+        uptime: process.uptime(),
+        ...stats,
+      }),
+    );
+    return;
+  }
+
+  // Slack events endpoint
+  if (req.method === "POST" && req.url === "/slack/events") {
+    let body = "";
+    req.on("data", (chunk) => {
+      body += chunk;
+    });
+    req.on("end", () => {
+      // Check for Slack retry header — if this is a retry and we already
+      // processed it, acknowledge immediately
+      const retryNum = req.headers["x-slack-retry-num"];
+      const retryReason = req.headers["x-slack-retry-reason"];
+      if (retryNum) {
+        log("WARN", `Slack retry #${retryNum} (reason: ${retryReason})`);
+        // If Slack is retrying because we were slow, just ack
+        // The original event was likely already processed
+        if (retryReason === "http_timeout") {
+          res.writeHead(200, { "X-Slack-No-Retry": "1" });
+          res.end("ok");
+          return;
+        }
+      }
+
+      // Verify Slack signature — always (SIGNING_SECRET is guaranteed set by
+      // the boot guard; verification never gets skipped).
+      const timestamp = req.headers["x-slack-request-timestamp"];
+      const signature = req.headers["x-slack-signature"];
+      if (!verifySlackSignature(timestamp, body, signature)) {
+        log("ERROR", "Invalid Slack signature — rejecting request");
+        stats.errors++;
+        res.writeHead(401);
+        res.end("Invalid signature");
+        return;
+      }
+
+      let payload;
+      try {
+        payload = JSON.parse(body);
+      } catch {
+        res.writeHead(400);
+        res.end("Bad JSON");
+        return;
+      }
+
+      // URL verification challenge (one-time setup when registering the endpoint)
+      if (payload.type === "url_verification") {
+        log("INFO", "URL verification challenge received");
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ challenge: payload.challenge }));
+        return;
+      }
+
+      // Event callback — respond 200 immediately, then process async
+      // Slack requires response within 3 seconds or it retries
+      res.writeHead(200, { "X-Slack-No-Retry": "1" });
+      res.end("ok");
+
+      // Process event asynchronously (after we've already sent 200)
+      if (payload.type === "event_callback") {
+        // Use setImmediate to ensure the response is sent before processing
+        setImmediate(() => {
+          try {
+            handleEvent(payload);
+          } catch (err) {
+            stats.errors++;
+            log("ERROR", `Unhandled error processing event: ${err.message}`, {
+              stack: err.stack,
+            });
+          }
+        });
+      }
+    });
+    return;
+  }
+
+  // Any other route
+  res.writeHead(404, { "Content-Type": "application/json" });
+  res.end(
+    JSON.stringify({
+      error: "Not found",
+      endpoints: ["/slack/events", "/health"],
+    }),
+  );
+});
+
+// ── Startup ───────────────────────────────────────────────────────────────────
+
+server.listen(PORT, () => {
+  log("INFO", `Slack Events Server started`, { port: PORT });
+  console.log(`[SLACK-EVENTS] Listening on port ${PORT}`);
+  console.log(
+    `[SLACK-EVENTS] Webhook URL: http://localhost:${PORT}/slack/events`,
+  );
+  console.log(`[SLACK-EVENTS] Health:      http://localhost:${PORT}/health`);
+  console.log(`[SLACK-EVENTS] Dedup dir:   ${DEDUP_DIR}`);
+  console.log(`[SLACK-EVENTS] Inbox dir:   ${INBOX_DIR}`);
+  console.log(`[SLACK-EVENTS] Trigger dir: ${TRIGGER_DIR}`);
+});
+
+// ── Graceful Shutdown ─────────────────────────────────────────────────────────
+
+function shutdown(signal) {
+  log("INFO", `Received ${signal}, shutting down gracefully...`);
+  server.close(() => {
+    log("INFO", "Server closed");
+    process.exit(0);
+  });
+  // Force exit after 5 seconds if server hasn't closed
+  setTimeout(() => {
+    log("WARN", "Forced shutdown after timeout");
+    process.exit(1);
+  }, 5000);
+}
+
+process.on("SIGTERM", () => shutdown("SIGTERM"));
+process.on("SIGINT", () => shutdown("SIGINT"));
+
+// Prevent unhandled rejections from crashing the server
+process.on("unhandledRejection", (err) => {
+  stats.errors++;
+  log("ERROR", `Unhandled rejection: ${err.message || err}`, {
+    stack: err.stack,
+  });
+});
+
+process.on("uncaughtException", (err) => {
+  stats.errors++;
+  log("ERROR", `Uncaught exception: ${err.message}`, { stack: err.stack });
+  // For uncaught exceptions, exit after logging — let launchd restart us
+  setTimeout(() => process.exit(1), 1000);
+});