@cohortapp/agent-sdk 2.3.0

package/scripts/huddle/huddle-server.mjs

@@ -0,0 +1,1229 @@
+#!/usr/bin/env node
+/**
+ * Agent Huddle — Main Server
+ *
+ * Orchestrates Slack huddle voice participation by coordinating:
+ *   - HuddleController (CDP-based Slack UI automation)
+ *   - AudioBridge (BlackHole capture → Deepgram STT → ElevenLabs TTS → BlackHole playback)
+ *   - Claude API (conversation intelligence, reused from voice-ai)
+ *
+ * Lifecycle:
+ *   1. Connects to Slack desktop app via CDP
+ *   2. Listens for huddle invitations (Events API + DOM polling)
+ *   3. On invitation or initiate command → joins huddle
+ *   4. Captures audio → transcribes → Claude generates response → TTS → speaks
+ *   5. On huddle end → saves transcript, routes action items
+ *
+ * Usage:
+ *   node huddle-server.mjs                    # Start and listen for huddles
+ *   node huddle-server.mjs --join #general    # Join huddle in #general
+ *   node huddle-server.mjs --call principal  # Initiate huddle with the agent's principal
+ */
+
+import dotenv from "dotenv";
+import { fileURLToPath as _fu } from "node:url";
+import { dirname as _dn, join as _jn } from "node:path";
+
+// Load .env from agent repo root (where all API keys live), then huddle-specific .env
+const _d = _dn(_fu(import.meta.url));
+dotenv.config({ path: _jn(_d, "../..", ".env") });
+dotenv.config({ path: _jn(_d, ".env"), override: true });
+import { EventEmitter } from "node:events";
+import { readFileSync, appendFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createServer } from "node:http";
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+import Anthropic from "@anthropic-ai/sdk";
+
+const execFileAsync = promisify(execFileCb);
+import { HuddleController } from "./huddle-controller.mjs";
+import { AudioBridge } from "./audio-bridge.mjs";
+import { OpenAIRealtimeHuddleBridge } from "./openai-realtime-bridge.mjs";
+
+// Brain selection. Default is "openai-realtime" — the same single-model
+// speech-to-speech path that drives PSTN. The legacy Deepgram+Claude+11Labs
+// pipeline is still selectable via HUDDLE_BRAIN=legacy for fallback.
+const HUDDLE_BRAIN = (process.env.HUDDLE_BRAIN || "openai-realtime").toLowerCase();
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_REPO_DIR = process.env.AGENT_DIR || join(__dirname, "../..");
+const VOICE_AI_ROOT = process.env.VOICE_AI_ROOT || join(process.env.HOME || "", "voice-ai");
+
+// Load agent identity for transcript speaker tags + display names.
+let _agent = null;
+function loadAgent() {
+  if (_agent) return _agent;
+  try {
+    _agent = JSON.parse(readFileSync(join(AGENT_REPO_DIR, "config/agent.json"), "utf-8"));
+  } catch {
+    _agent = { firstName: "Agent" };
+  }
+  return _agent;
+}
+const AGENT_SLUG = (loadAgent().firstName || "agent").toLowerCase();
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+const MAX_TOKENS = 300;
+const MAX_TOOL_ROUNDS = 3;
+const HUDDLE_EVENTS_PORT = parseInt(process.env.HUDDLE_EVENTS_PORT || "3200", 10);
+
+// Use Claude Code CLI (Max subscription) instead of API calls.
+// Falls back to API if claude CLI is not available.
+const USE_CLAUDE_CLI = process.env.HUDDLE_USE_API !== "1";
+const anthropic = USE_CLAUDE_CLI ? null : new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+
+// ---------------------------------------------------------------------------
+// Maestro action executor + tool definitions (colocated under lib/ since
+// 1.12.19). Falls back to the legacy ~/voice-ai install for old setups.
+// ---------------------------------------------------------------------------
+
+let executeAction = null;
+let getToolsForAccessLevel = null;
+let getToolNamesForAccessLevel = null;
+
+const _maestroExecutorCandidates = [
+  join(__dirname, "../../lib/action-executor.js"),
+  join(__dirname, "../../lib/action-executor.mjs"),
+  join(VOICE_AI_ROOT, "lib/action-executor.js"),
+];
+const _maestroToolsCandidates = [
+  join(__dirname, "../../lib/tool-definitions.js"),
+  join(__dirname, "../../lib/tool-definitions.mjs"),
+  join(VOICE_AI_ROOT, "lib/tool-definitions.js"),
+];
+
+for (const candidate of _maestroExecutorCandidates) {
+  if (!existsSync(candidate)) continue;
+  try {
+    const mod = await import(candidate);
+    executeAction = mod.executeAction;
+    if (executeAction) break;
+  } catch { /* try next */ }
+}
+for (const candidate of _maestroToolsCandidates) {
+  if (!existsSync(candidate)) continue;
+  try {
+    const mod = await import(candidate);
+    getToolsForAccessLevel = mod.getToolsForAccessLevel;
+    getToolNamesForAccessLevel = mod.getToolNamesForAccessLevel;
+    if (getToolsForAccessLevel) break;
+  } catch { /* try next */ }
+}
+if (executeAction && getToolsForAccessLevel) {
+  console.log("[INIT] action executor + tool definitions loaded");
+} else {
+  console.warn("[INIT] action executor / tool definitions not available — huddle will be read-only");
+}
+
+// ---------------------------------------------------------------------------
+// Huddle Session State
+// ---------------------------------------------------------------------------
+
+/** @enum {string} */
+const HuddleState = {
+  IDLE: "idle",
+  JOINING: "joining",
+  ACTIVE: "active",
+  LEAVING: "leaving",
+};
+
+/**
+ * HuddleServer is the top-level orchestrator for the agent's huddle participation.
+ */
+class HuddleServer extends EventEmitter {
+  constructor() {
+    super();
+    this.controller = new HuddleController();
+    // Brain selection: openai-realtime (default) is the single-model
+    // speech-to-speech path identical to PSTN inbound; legacy retains the
+    // older Deepgram+Claude+ElevenLabs three-stage pipeline.
+    if (HUDDLE_BRAIN === "openai-realtime") {
+      this.bridge = new OpenAIRealtimeHuddleBridge({
+        apiKey: process.env.OPENAI_API_KEY,
+        agentRoot: AGENT_REPO_DIR,
+        // tools + executor wired lazily in start() so we don't pull
+        // action-executor at import time.
+      });
+      this._brainKind = "openai-realtime";
+    } else {
+      // Pass API keys explicitly because ESM import hoisting evaluates
+      // audio-bridge.mjs before dotenv.config() runs in this file.
+      this.bridge = new AudioBridge({
+        deepgramKey: process.env.DEEPGRAM_API_KEY,
+        elevenLabsKey: process.env.ELEVENLABS_API_KEY,
+      });
+      this._brainKind = "legacy";
+    }
+
+    this.state = HuddleState.IDLE;
+    this.session = null; // Active huddle session
+    this.autoJoin = true; // Auto-join incoming huddle invitations
+  }
+
+  // -------------------------------------------------------------------------
+  // Startup
+  // -------------------------------------------------------------------------
+
+  async start() {
+    console.log("\n==========================================");
+    console.log(`  ${loadAgent().firstName || "Agent"} Huddle Server`);
+    console.log("  " + new Date().toISOString());
+    console.log("==========================================\n");
+
+    // Verify audio devices
+    const devices = await this.bridge.checkDevices();
+    if (!devices.capture || !devices.playback) {
+      console.error("[INIT] Audio devices missing:");
+      console.error(`  Capture (BlackHole 2ch):  ${devices.capture ? "OK" : "MISSING"}`);
+      console.error(`  Playback (BlackHole 16ch): ${devices.playback ? "OK" : "MISSING"}`);
+      console.error("Run: ./setup-audio.sh to install");
+      process.exit(1);
+    }
+    console.log("[INIT] Audio devices verified");
+    console.log(`[INIT] LLM mode: ${USE_CLAUDE_CLI ? "Claude Code CLI (Max subscription)" : "Anthropic API (pay-per-token)"}`);
+
+    // Connect to Slack via CDP
+    this._wireControllerEvents();
+    const connected = await this.controller.connect();
+    if (!connected) {
+      console.error("[INIT] Failed to connect to Slack via CDP");
+      console.error("Run: ./launch-slack.sh to start Slack with CDP enabled");
+      process.exit(1);
+    }
+    console.log("[INIT] Connected to Slack via CDP");
+
+    // Wire audio bridge events
+    this._wireBridgeEvents();
+
+    // Start Events API listener for reliable huddle detection
+    this._startEventsListener();
+
+    console.log("[INIT] Huddle server ready — listening for invitations\n");
+
+    // Handle CLI arguments
+    const args = process.argv.slice(2);
+    if (args[0] === "--join" && args[1]) {
+      await this.joinHuddle(args[1]);
+    } else if (args[0] === "--call" && args[1]) {
+      await this.initiateHuddle(args[1]);
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Huddle lifecycle
+  // -------------------------------------------------------------------------
+
+  /**
+   * Join an existing huddle in a channel or DM.
+   * @param {string} channel - Channel name or person name
+   */
+  async joinHuddle(channel) {
+    if (this.state !== HuddleState.IDLE) {
+      console.log(`[HUDDLE] Cannot join — currently ${this.state}`);
+      return;
+    }
+
+    this.state = HuddleState.JOINING;
+    console.log(`[HUDDLE] Joining huddle in: ${channel}`);
+
+    try {
+      const joined = await this.controller.joinHuddle(channel);
+      if (!joined) {
+        console.error("[HUDDLE] Failed to join huddle");
+        this.state = HuddleState.IDLE;
+        return;
+      }
+
+      await this._startSession(channel, "joined");
+    } catch (err) {
+      console.error(`[HUDDLE] Join error: ${err.message}`);
+      this.state = HuddleState.IDLE;
+    }
+  }
+
+  /**
+   * Initiate a new huddle with a person or in a channel.
+   * @param {string} target - Channel name or person name
+   */
+  async initiateHuddle(target) {
+    if (this.state !== HuddleState.IDLE) {
+      console.log(`[HUDDLE] Cannot initiate — currently ${this.state}`);
+      return;
+    }
+
+    this.state = HuddleState.JOINING;
+    console.log(`[HUDDLE] Initiating huddle with: ${target}`);
+
+    try {
+      const started = await this.controller.initiateHuddle(target);
+      if (!started) {
+        console.error("[HUDDLE] Failed to start huddle");
+        this.state = HuddleState.IDLE;
+        return;
+      }
+
+      await this._startSession(target, "initiated");
+    } catch (err) {
+      console.error(`[HUDDLE] Initiate error: ${err.message}`);
+      this.state = HuddleState.IDLE;
+    }
+  }
+
+  /**
+   * Leave the current huddle.
+   */
+  async leaveHuddle() {
+    if (this.state !== HuddleState.ACTIVE) return;
+
+    this.state = HuddleState.LEAVING;
+    console.log("[HUDDLE] Leaving huddle...");
+
+    try {
+      await this.controller.leaveHuddle();
+    } catch (err) {
+      console.error(`[HUDDLE] Leave error: ${err.message}`);
+    }
+
+    await this._endSession();
+    this.state = HuddleState.IDLE;
+  }
+
+  // -------------------------------------------------------------------------
+  // Session management
+  // -------------------------------------------------------------------------
+
+  async _startSession(channel, mode, initiator = null) {
+    // Guard: don't start a duplicate session
+    if (this.state === HuddleState.ACTIVE && this.session) {
+      console.log(`[HUDDLE] Session already active — ignoring duplicate start`);
+      return;
+    }
+    this.state = HuddleState.ACTIVE;
+
+    // Resolve who initiated the huddle for access control
+    const callerInfo = this._resolveHuddleParticipant(initiator || channel);
+
+    this.session = {
+      channel,
+      mode, // "joined" or "initiated"
+      startedAt: new Date().toISOString(),
+      messages: [],
+      transcript: [],
+      participants: [],
+      accessLevel: callerInfo.accessLevel,
+      callerSlug: callerInfo.slug,
+      callerName: callerInfo.name,
+      threadPollTimer: null,       // Huddle thread message polling
+      lastThreadTs: null,          // Last seen thread message timestamp
+    };
+
+    // Load live context from the agent repo for Claude
+    this.session.liveContext = this._loadLiveContext();
+
+    // In webaudio capture mode (legacy bridge only), set Slack's speaker to
+    // physical output (eliminates AEC echo). Audio is captured directly from
+    // the WebRTC stream via CDP, so BlackHole 2ch is not needed for the
+    // speaker path.
+    if (this.bridge.captureMode === "webaudio") {
+      await this._setSlackSpeakerToDefault();
+    }
+
+    // Wire the openai-realtime brain with tools + executor + per-call
+    // identity (channel, peer, brief). Done here rather than at bridge
+    // construction so each new huddle session can pull fresh context.
+    if (this._brainKind === "openai-realtime") {
+      await this._configureRealtimeBrain(channel, mode);
+    }
+
+    // Start audio bridge
+    await this.bridge.start();
+
+    console.log(`[HUDDLE] Session active in ${channel} (${mode})`);
+    this._logEvent("session-started", { channel, mode });
+
+    // Speak a greeting
+    const greeting = mode === "initiated"
+      ? `Hey, do you have a moment?`
+      : `Hey, what's up?`;
+
+    await this.bridge.speak(greeting);
+    if (this.session) {
+      this.session.messages.push({ role: "assistant", content: greeting });
+      this.session.transcript.push({ speaker: AGENT_SLUG, text: greeting, ts: Date.now() });
+    }
+
+    // Start polling the huddle thread for text messages
+    this._startThreadPolling();
+  }
+
+  async _endSession() {
+    if (!this.session) return;
+
+    // Stop thread polling
+    if (this.session.threadPollTimer) {
+      clearInterval(this.session.threadPollTimer);
+      this.session.threadPollTimer = null;
+    }
+
+    // Stop audio bridge
+    await this.bridge.stop();
+
+    // Save transcript
+    this._saveTranscript();
+
+    // Log session end
+    const duration = Math.round((Date.now() - new Date(this.session.startedAt).getTime()) / 1000);
+    const turns = this.session.messages.length;
+    console.log(`[HUDDLE] Session ended — ${duration}s, ${turns} turns`);
+    this._logEvent("session-ended", {
+      channel: this.session.channel,
+      duration,
+      turns,
+    });
+
+    this.session = null;
+  }
+
+  // -------------------------------------------------------------------------
+  // Conversation loop (adapted from voice-ai/lib/claude.js)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Configure the OpenAI Realtime bridge before start() — loads tools
+   * appropriate for voice + wires the action executor so the model can
+   * place follow-ups, send Slack messages, query RAG, etc. mid-huddle.
+   * The bridge itself loads identity + queues + team + RAG via
+   * lib/voice/context-loader.mjs at start().
+   */
+  async _configureRealtimeBrain(channel, mode) {
+    try {
+      const [{ actionsToRealtimeTools }, { executeAction }] = await Promise.all([
+        import("../../lib/voice/tool-bridge.mjs"),
+        import("../../lib/action-executor.js"),
+      ]);
+      const tools = await actionsToRealtimeTools({
+        accessLevel: "voice",
+        agentRoot: AGENT_REPO_DIR,
+      });
+      this.bridge.tools = tools;
+      this.bridge.peer = channel || null;
+      this.bridge.brief = mode === "initiated"
+        ? "You're initiating a casual huddle. Open with a quick check-in."
+        : `You've been invited to a huddle in ${channel}. Listen, then respond naturally.`;
+      this.bridge.executeTool = async ({ name, arguments: args, call_id }) => {
+        try {
+          const result = await executeAction(
+            name,
+            args,
+            { accessLevel: "voice", source: "huddle", channelId: channel },
+            `huddle-${this.session?.id || Date.now()}`,
+            { agentRoot: AGENT_REPO_DIR },
+          );
+          this._logEvent("tool-executed", { name, call_id, success: result?.success });
+          return typeof result === "string" ? result : JSON.stringify(result || {});
+        } catch (err) {
+          this._logEvent("tool-failed", { name, call_id, error: err.message });
+          return JSON.stringify({ ok: false, error: err.message });
+        }
+      };
+    } catch (err) {
+      console.warn(`[HUDDLE] failed to wire realtime tools: ${err.message}`);
+    }
+  }
+
+  /**
+   * Process a transcript from the huddle and generate the agent's response.
+   *
+   * Only used by the legacy Deepgram+Claude+11Labs brain. The openai-realtime
+   * brain handles speech-in → speech-out internally; this handler is a no-op
+   * for it (the bridge emits 'transcript' events for logging only).
+   *
+   * @param {string} userText - What someone said in the huddle
+   */
+  async _handleTranscript(userText) {
+    if (!this.session || this.state !== HuddleState.ACTIVE) return;
+    if (!userText || !userText.trim()) return;
+
+    // openai-realtime: just append to transcript, no Claude round-trip
+    if (this._brainKind === "openai-realtime") {
+      this.session.transcript.push({ speaker: "participant", text: userText, ts: Date.now() });
+      return;
+    }
+
+    console.log(`[SPEECH] "${userText}"`);
+
+    // Add to conversation history
+    this.session.messages.push({ role: "user", content: userText });
+    this.session.transcript.push({ speaker: "participant", text: userText, ts: Date.now() });
+
+    try {
+      // Get Claude's response
+      const responseText = await this._getClaudeResponse(this.session.messages);
+
+      if (!responseText || !responseText.trim()) return;
+
+      console.log(`[AGENT] "${responseText}"`);
+
+      // Check for end signal
+      const shouldEnd = responseText.includes("END_HUDDLE");
+      const cleanResponse = responseText.replace(/\s*END_HUDDLE\s*/g, "").trim();
+
+      // Add to history
+      this.session.messages.push({ role: "assistant", content: cleanResponse });
+      this.session.transcript.push({ speaker: AGENT_SLUG, text: cleanResponse, ts: Date.now() });
+
+      // Speak the response via TTS → BlackHole 16ch → Slack mic
+      await this.bridge.speak(cleanResponse);
+
+      if (shouldEnd) {
+        // Wait for TTS to finish, then leave
+        setTimeout(() => this.leaveHuddle(), 2000);
+      }
+    } catch (err) {
+      console.error(`[CLAUDE] Error: ${err.message}`);
+
+      const fallback = "Sorry, give me one second — I'm having a brief technical hiccup.";
+      await this.bridge.speak(fallback);
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Huddle thread text message monitoring
+  // -------------------------------------------------------------------------
+
+  /**
+   * Start polling the huddle thread for text messages via the Slack API.
+   * Text messages in the huddle thread are injected into the conversation
+   * so the agent can respond to both voice and text.
+   */
+  _startThreadPolling() {
+    const slackToken = process.env.SLACK_USER_TOKEN || process.env.SLACK_BOT_TOKEN;
+    if (!slackToken) {
+      console.log("[THREAD] No Slack token — thread monitoring disabled");
+      return;
+    }
+
+    // Determine the huddle channel ID from the current Slack page
+    this._resolveHuddleChannelId().then((channelId) => {
+      if (!channelId) {
+        console.log("[THREAD] Could not resolve huddle channel — thread monitoring disabled");
+        return;
+      }
+
+      console.log(`[THREAD] Monitoring huddle thread in ${channelId}`);
+      this.session.lastThreadTs = String(Date.now() / 1000); // Start from now
+
+      this.session.threadPollTimer = setInterval(async () => {
+        try {
+          await this._pollThreadMessages(channelId, slackToken);
+        } catch (err) {
+          console.error(`[THREAD] Poll error: ${err.message}`);
+        }
+      }, 5000); // Poll every 5 seconds
+    });
+  }
+
+  /**
+   * Resolve the current huddle's channel ID from the Slack page via CDP.
+   * @returns {Promise<string|null>}
+   */
+  async _resolveHuddleChannelId() {
+    try {
+      const targets = await fetch("http://localhost:9222/json").then((r) => r.json());
+      const mainTarget = targets.find(
+        (t) => t.type === "page" && t.url?.includes("app.slack.com/client")
+      );
+      if (!mainTarget) return null;
+
+      // Extract channel ID from the URL: /client/TEAM_ID/CHANNEL_ID
+      const match = mainTarget.url.match(/\/client\/[A-Z0-9]+\/([A-Z0-9]+)/);
+      return match ? match[1] : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Poll the Slack channel for recent messages in the huddle thread.
+   * Only processes text messages from other users (not the agent's bot).
+   */
+  async _pollThreadMessages(channelId, token) {
+    if (!this.session) return;
+
+    const oldest = this.session.lastThreadTs || "0";
+    const url = `https://slack.com/api/conversations.history?channel=${channelId}&oldest=${oldest}&limit=10`;
+
+    const resp = await fetch(url, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    const data = await resp.json();
+    if (!data.ok || !data.messages || data.messages.length === 0) return;
+
+    // The agent's Slack user ID (skip its own messages). Hardcoded fallback
+    // removed — agents must set SLACK_BOT_USER_ID in .env if they want this
+    // filter active, otherwise the agent's slackMemberId from agent.json is used.
+    const agentUserId = process.env.SLACK_BOT_USER_ID || loadAgent().slackMemberId || "";
+
+    for (const msg of data.messages.reverse()) { // oldest first
+      // Skip bot messages, the agent's own messages, and non-text messages
+      if (agentUserId && msg.user === agentUserId) continue;
+      if (msg.subtype) continue; // Skip system messages
+      if (!msg.text || !msg.text.trim()) continue;
+
+      // Update last seen timestamp
+      this.session.lastThreadTs = msg.ts;
+
+      // Handle the text message like a voice transcript
+      const senderName = msg.user_profile?.display_name || msg.user || "someone";
+      const textContent = `[Text message from ${senderName}]: ${msg.text}`;
+
+      console.log(`[THREAD] ${textContent}`);
+      this.session.transcript.push({ speaker: "text", text: textContent, ts: Date.now() });
+
+      // Add to conversation and generate response
+      await this._handleTranscript(textContent);
+    }
+  }
+
+  /**
+   * Get a response from Claude given the conversation history.
+   * Uses Claude Code CLI (Max subscription) by default, falling back
+   * to the Anthropic API if CLI is unavailable or HUDDLE_USE_API=1.
+   *
+   * @param {Array} messages - Conversation history [{role, content}]
+   * @returns {Promise<string>} Response text
+   */
+  async _getClaudeResponse(messages) {
+    if (USE_CLAUDE_CLI) {
+      return this._getClaudeResponseCLI(messages);
+    }
+    return this._getClaudeResponseAPI(messages);
+  }
+
+  /**
+   * Get a response via Claude Code CLI (uses Max subscription).
+   * Constructs a prompt from system + conversation history and pipes
+   * it through `claude --print`.
+   */
+  async _getClaudeResponseCLI(messages) {
+    const systemPrompt = this._buildSystemPrompt();
+
+    // Build a single prompt from system + conversation history
+    const parts = [`[System]\n${systemPrompt}\n`];
+    for (const msg of messages) {
+      const role = msg.role === "assistant" ? (loadAgent().firstName || "Agent") : "Participant";
+      const content = typeof msg.content === "string"
+        ? msg.content
+        : msg.content?.map((b) => b.text || "").join("") || "";
+      if (content.trim()) {
+        parts.push(`[${role}]\n${content}`);
+      }
+    }
+    parts.push(`[${loadAgent().firstName || "Agent"}]`);
+
+    const prompt = parts.join("\n\n");
+
+    const { stdout } = await execFileAsync("claude", [
+      "--print",
+      "--model", "sonnet",
+      "-p", prompt,
+    ], {
+      timeout: 30000,
+      maxBuffer: 1024 * 1024,
+      env: { ...process.env, TERM: "dumb" },
+    });
+
+    return (stdout || "").trim();
+  }
+
+  /**
+   * Get a response via Anthropic API (pay-per-token fallback).
+   * Supports tool use with multi-round execution.
+   */
+  async _getClaudeResponseAPI(messages) {
+    const systemPrompt = this._buildSystemPrompt();
+    const accessLevel = this.session?.accessLevel || "default";
+    const tools = getToolsForAccessLevel ? getToolsForAccessLevel(accessLevel) : [];
+
+    const apiParams = {
+      model: "claude-sonnet-4-20250514",
+      max_tokens: MAX_TOKENS,
+      system: systemPrompt,
+      messages: [...messages],
+    };
+
+    if (tools.length > 0) {
+      apiParams.tools = tools;
+    }
+
+    let fullResponse = "";
+    let round = 0;
+
+    while (round < MAX_TOOL_ROUNDS) {
+      round++;
+      const response = await anthropic.messages.create(apiParams);
+
+      const textParts = [];
+      const toolUseBlocks = [];
+
+      for (const block of response.content) {
+        if (block.type === "text") {
+          textParts.push(block.text);
+        } else if (block.type === "tool_use") {
+          toolUseBlocks.push(block);
+        }
+      }
+
+      const roundText = textParts.join("");
+      fullResponse += roundText;
+
+      if (toolUseBlocks.length === 0) break;
+
+      if (roundText.trim()) {
+        const filler = roundText.replace(/\s*END_HUDDLE\s*/g, "").trim();
+        if (filler) {
+          await this.bridge.speak(filler);
+          if (this.session) {
+            this.session.transcript.push({ speaker: AGENT_SLUG, text: filler, ts: Date.now() });
+          }
+        }
+      }
+
+      const assistantContent = [];
+      if (roundText.trim()) {
+        assistantContent.push({ type: "text", text: roundText });
+      }
+      for (const tb of toolUseBlocks) {
+        assistantContent.push({ type: "tool_use", id: tb.id, name: tb.name, input: tb.input });
+      }
+      apiParams.messages.push({ role: "assistant", content: assistantContent });
+
+      const toolResults = [];
+      for (const tb of toolUseBlocks) {
+        console.log(`[TOOL] Executing: ${tb.name}`);
+        this._logEvent("tool-call", { tool: tb.name, input: tb.input });
+
+        if (executeAction) {
+          const callerInfo = {
+            slug: this.session?.callerSlug || "huddle-participant",
+            name: this.session?.callerName || "Huddle Participant",
+            accessLevel,
+          };
+          const result = await executeAction(tb.name, tb.input, callerInfo, `huddle-${Date.now()}`);
+          toolResults.push({ type: "tool_result", tool_use_id: tb.id, content: result.result });
+          console.log(`[TOOL] ${tb.name}: ${result.success ? "OK" : "FAILED"}`);
+        } else {
+          toolResults.push({
+            type: "tool_result",
+            tool_use_id: tb.id,
+            content: "Tool execution not available in this session.",
+          });
+        }
+      }
+
+      apiParams.messages.push({ role: "user", content: toolResults });
+    }
+
+    return fullResponse.trim();
+  }
+
+  // -------------------------------------------------------------------------
+  // Participant resolution (for access control + personalization)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Resolve a huddle participant's identity from the agent repo contacts/profiles.
+   * Used for access control (CEO gets write tools) and personalized greetings.
+   */
+  _resolveHuddleParticipant(identifier) {
+    // Seed `knownParticipants` with the agent's PRINCIPAL from
+    // config/agent.json (SOT) — replaces the previously-hardcoded "alex"
+    // entry. Falls back to common operational handles for back-compat.
+    const knownParticipants = {
+      "#ceo-office": { slug: "ceo-office", name: "CEO Office Channel", accessLevel: "ceo" },
+    };
+    try {
+      const agentPath = join(AGENT_REPO_DIR, "config/agent.json");
+      const agentJson = JSON.parse(readFileSync(agentPath, "utf-8"));
+      const principal = agentJson?.principal;
+      if (principal?.firstName) {
+        const slug = `${principal.firstName}-${principal.lastName || ""}`.toLowerCase().replace(/\s+/g, "-").replace(/-+$/, "");
+        const entry = {
+          slug,
+          name: principal.fullName || `${principal.firstName} ${principal.lastName || ""}`.trim(),
+          accessLevel: "ceo",
+        };
+        knownParticipants[principal.firstName.toLowerCase()] = entry;
+        knownParticipants[slug] = entry;
+        knownParticipants["principal"] = entry;
+      }
+    } catch { /* agent.json unavailable — only #ceo-office remains */ }
+
+    const key = (identifier || "").toLowerCase().replace(/^#/, "");
+    const match = knownParticipants[key];
+
+    if (match) return match;
+
+    // Try loading from contacts.yaml
+    try {
+      const contactsPath = join(AGENT_REPO_DIR, "config/contacts.yaml");
+      const contacts = readFileSync(contactsPath, "utf8");
+      // Simple search — look for the identifier in the contacts file
+      if (contacts.toLowerCase().includes(key)) {
+        // If found in contacts, give default access
+        return { slug: key, name: identifier, accessLevel: "default" };
+      }
+    } catch { /* optional */ }
+
+    return { slug: "unknown", name: identifier || "Unknown", accessLevel: "default" };
+  }
+
+  // -------------------------------------------------------------------------
+  // Slack Events API listener (huddle detection)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Start a lightweight HTTP server that receives forwarded huddle events
+   * from the main slack-events-server.mjs. This provides a more reliable
+   * huddle detection path than DOM polling alone.
+   */
+  _startEventsListener() {
+    this.eventsServer = createServer((req, res) => {
+      if (req.method !== "POST" || req.url !== "/huddle-event") {
+        res.writeHead(404);
+        res.end();
+        return;
+      }
+
+      let body = "";
+      req.on("data", (chunk) => { body += chunk; });
+      req.on("end", () => {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end('{"ok":true}');
+
+        try {
+          const event = JSON.parse(body);
+          this._handleHuddleEvent(event);
+        } catch (err) {
+          console.error(`[EVENTS] Parse error: ${err.message}`);
+        }
+      });
+    });
+
+    this.eventsServer.listen(HUDDLE_EVENTS_PORT, "127.0.0.1", () => {
+      console.log(`[EVENTS] Huddle event listener on port ${HUDDLE_EVENTS_PORT}`);
+    });
+  }
+
+  /**
+   * Handle a huddle event forwarded from the Slack Events API.
+   * Event shape: { user, huddle_state, channel, channel_type }
+   */
+  _handleHuddleEvent(event) {
+    const { user, user_name, huddle_state, channel, channel_type } = event;
+
+    console.log(`[EVENTS] Huddle event: ${user_name || user} → ${huddle_state} in ${channel || "unknown"}`);
+    this._logEvent("events-api-huddle", event);
+
+    // Someone started a huddle and the agent isn't in one yet
+    if (huddle_state === "in_a_huddle" && this.state === HuddleState.IDLE && this.autoJoin) {
+      // Determine the channel to join
+      const targetChannel = channel || user_name;
+      if (targetChannel) {
+        console.log(`[EVENTS] Huddle detected — auto-joining ${targetChannel}`);
+        this.joinHuddle(targetChannel);
+      }
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // System prompt (adapted for huddle context)
+  // -------------------------------------------------------------------------
+
+  _buildSystemPrompt() {
+    const liveContextBlock = this.session?.liveContext
+      ? `\n\nLIVE CONTEXT:\n${this.session.liveContext}`
+      : "";
+
+    return `${HUDDLE_SYSTEM_PROMPT}${liveContextBlock}`;
+  }
+
+  // -------------------------------------------------------------------------
+  // Live context loader (reads from the agent repo state files)
+  // -------------------------------------------------------------------------
+
+  _loadLiveContext() {
+    const contextParts = [];
+
+    // Load priorities
+    try {
+      const priorities = readFileSync(join(AGENT_REPO_DIR, "config/priorities.yaml"), "utf8");
+      contextParts.push(`PRIORITIES:\n${priorities.slice(0, 2000)}`);
+    } catch { /* optional */ }
+
+    // Load executive summary
+    try {
+      const summary = readFileSync(join(AGENT_REPO_DIR, "state/dashboards/executive-summary.yaml"), "utf8");
+      contextParts.push(`EXECUTIVE SUMMARY:\n${summary.slice(0, 3000)}`);
+    } catch { /* optional */ }
+
+    return contextParts.join("\n\n");
+  }
+
+  // -------------------------------------------------------------------------
+  // Event wiring
+  // -------------------------------------------------------------------------
+
+  _wireControllerEvents() {
+    this.controller.on("connected", () => {
+      console.log("[CDP] Connected to Slack");
+    });
+
+    this.controller.on("disconnected", () => {
+      console.log("[CDP] Disconnected from Slack — reconnecting...");
+    });
+
+    this.controller.on("huddle:invitation", async (data) => {
+      console.log(`[HUDDLE] Incoming invitation from ${data.from} in ${data.channel}`);
+      this._logEvent("invitation-received", data);
+
+      if (this.autoJoin && this.state === HuddleState.IDLE) {
+        console.log("[HUDDLE] Auto-joining...");
+        await this.controller.acceptInvitation();
+        await this._startSession(data.channel, "joined");
+      }
+    });
+
+    this.controller.on("huddle:joined", async (data) => {
+      console.log(`[HUDDLE] Active huddle detected: ${data.channel}`);
+      if (this.state === HuddleState.IDLE) {
+        await this._startSession(data.channel, "joined");
+      }
+    });
+
+    this.controller.on("huddle:left", async () => {
+      if (this.state === HuddleState.ACTIVE) {
+        // Debounce: the polling can falsely detect "left" when the huddle
+        // runs in a separate window and the main window DOM is temporarily
+        // empty. Wait 5 seconds and re-check before ending the session.
+        console.log("[HUDDLE] Huddle may have ended — verifying in 5s...");
+        await new Promise((r) => setTimeout(r, 5000));
+        const stillActive = await this.controller.isInHuddle();
+        if (!stillActive && this.state === HuddleState.ACTIVE) {
+          console.log("[HUDDLE] Confirmed: huddle ended");
+          await this._endSession();
+          this.state = HuddleState.IDLE;
+        } else {
+          console.log("[HUDDLE] False alarm — huddle is still active");
+        }
+      }
+    });
+
+    this.controller.on("error", (err) => {
+      console.error(`[CDP] Error: ${err.message} — ${err.detail || ""}`);
+    });
+  }
+
+  _wireBridgeEvents() {
+    this.bridge.on("transcript", (data) => {
+      // openai-realtime emits {role, text} — split user vs assistant
+      // legacy bridge emits {text} for user-side only
+      if (this._brainKind === "openai-realtime") {
+        if (!this.session) return;
+        const speaker = data.role === "assistant" ? AGENT_SLUG : "participant";
+        this.session.transcript.push({ speaker, text: data.text, ts: Date.now() });
+        if (data.role === "assistant") {
+          console.log(`[${AGENT_SLUG.toUpperCase()}] "${data.text}"`);
+        } else {
+          console.log(`[SPEECH] "${data.text}"`);
+        }
+        return;
+      }
+      // Legacy: drive the Claude conversation loop
+      this._handleTranscript(data.text);
+    });
+
+    this.bridge.on("transcript:interim", (data) => {
+      // Interim transcript — show for debugging
+      process.stdout.write(`\r[INTERIM] ${data.text}       `);
+    });
+
+    this.bridge.on("tool:call", (data) => {
+      console.log(`[TOOL] ${data.name}(${(data.arguments || "").slice(0, 80)})`);
+    });
+
+    this.bridge.on("speech:start", () => {
+      // Someone started talking
+    });
+
+    this.bridge.on("speech:end", () => {
+      process.stdout.write("\r" + " ".repeat(80) + "\r"); // Clear interim line
+    });
+
+    this.bridge.on("tts:start", async (data) => {
+      // Legacy bridge emits {text: ...} (a discrete utterance about to play);
+      // openai-realtime emits empty (continuous audio stream just opened).
+      const preview = data?.text ? `"${data.text.substring(0, 60)}…"` : "(audio stream live)";
+      console.log(`[TTS] ${preview}`);
+      // Unmute Slack mic so TTS audio reaches the huddle
+      await this._setSlackMicMute(false);
+    });
+
+    this.bridge.on("tts:end", async () => {
+      // Re-mute Slack mic after TTS to prevent echo
+      // Small delay to ensure the last audio samples are transmitted
+      setTimeout(() => this._setSlackMicMute(true), 300);
+    });
+
+    this.bridge.on("error", (err) => {
+      console.error(`[BRIDGE] ${err.component} error: ${err.message}`);
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Slack mic mute control (half-duplex echo prevention)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Toggle the agent's Slack mic mute via CDP on the huddle window.
+   * Keeps mic muted between TTS outputs to prevent echo from the
+   * virtual audio loopback.
+   * @param {boolean} muted - true to mute, false to unmute
+   */
+  async _setSlackMicMute(muted) {
+    // In webaudio mode, mic muting for echo prevention is unnecessary —
+    // the echo is eliminated at the capture level, not the mic level.
+    if (this.bridge.captureMode === "webaudio") return;
+    try {
+      const targets = await fetch("http://localhost:9222/json").then((r) => r.json());
+      const huddleTarget = targets.find(
+        (t) => t.type === "page" && (t.title?.includes("Huddle:") || t.title?.includes("🎤"))
+      );
+      if (!huddleTarget) return;
+
+      const ws = new (await import("ws")).WebSocket(huddleTarget.webSocketDebuggerUrl);
+      await new Promise((resolve, reject) => {
+        ws.on("error", reject);
+        ws.on("open", () => {
+          ws.send(JSON.stringify({
+            id: 1,
+            method: "Runtime.evaluate",
+            params: {
+              expression: `(() => {
+                const muteBtn = document.querySelector('[data-qa="segmented-mute-button-main"]');
+                if (!muteBtn) return "no-mute-btn";
+                const label = (muteBtn.getAttribute("aria-label") || "").toLowerCase();
+                const currentlyMuted = label.includes("unmute");
+                if (currentlyMuted === ${muted}) return "already-${muted ? "muted" : "unmuted"}";
+                muteBtn.click();
+                return "${muted ? "muted" : "unmuted"}";
+              })()`,
+              returnByValue: true,
+            },
+          }));
+        });
+        ws.on("message", (data) => {
+          const msg = JSON.parse(data.toString());
+          if (msg.id === 1) {
+            const result = msg.result?.result?.value || "unknown";
+            if (result !== "already-muted" && result !== "already-unmuted") {
+              console.log(`[MIC] ${result}`);
+            }
+            ws.close();
+            resolve();
+          }
+        });
+      });
+    } catch {
+      // Non-fatal — mute toggle failed silently
+    }
+  }
+
+  /**
+   * Set Slack's speaker output to "default" (physical speakers) via CDP.
+   * Used in webaudio capture mode to eliminate AEC echo — audio is captured
+   * directly from the WebRTC stream, so BlackHole 2ch isn't needed.
+   */
+  async _setSlackSpeakerToDefault() {
+    try {
+      const targets = await fetch("http://localhost:9222/json").then((r) => r.json());
+      const mainTarget = targets.find(
+        (t) => t.type === "page" && t.url?.includes("app.slack.com/client")
+      );
+      if (!mainTarget) return;
+
+      const ws = new (await import("ws")).WebSocket(mainTarget.webSocketDebuggerUrl);
+      await new Promise((resolve) => {
+        ws.on("error", () => resolve());
+        ws.on("open", () => {
+          ws.send(JSON.stringify({
+            id: 1,
+            method: "Runtime.evaluate",
+            params: {
+              expression: `(async () => {
+                // Set speaker preference to default (physical speakers)
+                const inputId = "9f391a3f2efb9f50f9dc8dea1534700bcc5d4e0478b56438930a2071401b25bb";
+                localStorage.setItem("preferred-media-devices",
+                  JSON.stringify({ audioinput: inputId, audiooutput: "default" }));
+
+                // Also change the active audio element's output immediately
+                for (const audio of document.querySelectorAll("audio")) {
+                  try { await audio.setSinkId("default"); } catch {}
+                }
+                return "speaker set to default";
+              })()`,
+              returnByValue: true,
+              awaitPromise: true,
+            },
+          }));
+        });
+        ws.on("message", (data) => {
+          const msg = JSON.parse(data.toString());
+          if (msg.id === 1) {
+            console.log(`[AUDIO] Slack speaker → physical (${msg.result?.result?.value})`);
+            ws.close();
+            resolve();
+          }
+        });
+      });
+    } catch {
+      // Non-fatal
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Logging & transcript persistence
+  // -------------------------------------------------------------------------
+
+  _logEvent(event, data = {}) {
+    const logDir = join(AGENT_REPO_DIR, "logs/huddle");
+    mkdirSync(logDir, { recursive: true });
+
+    const date = new Date().toISOString().split("T")[0];
+    const logFile = join(logDir, `${date}-huddle-events.jsonl`);
+
+    const entry = {
+      timestamp: new Date().toISOString(),
+      event,
+      ...data,
+    };
+
+    appendFileSync(logFile, JSON.stringify(entry) + "\n");
+  }
+
+  _saveTranscript() {
+    if (!this.session || this.session.transcript.length === 0) return;
+
+    const logDir = join(AGENT_REPO_DIR, "logs/huddle");
+    mkdirSync(logDir, { recursive: true });
+
+    const date = new Date().toISOString().split("T")[0];
+    const ts = Date.now();
+    const channel = (this.session.channel || "unknown").replace(/[^a-zA-Z0-9-]/g, "_");
+    const transcriptFile = join(logDir, `${date}-transcript-${channel}-${ts}.jsonl`);
+
+    for (const entry of this.session.transcript) {
+      appendFileSync(transcriptFile, JSON.stringify(entry) + "\n");
+    }
+
+    console.log(`[TRANSCRIPT] Saved to ${transcriptFile}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Huddle-specific system prompt
+// ---------------------------------------------------------------------------
+
+function buildHuddleSystemPrompt() {
+  const a = loadAgent();
+  const principal = a.principal || {};
+  return `You are ${a.fullName}, ${a.title} to ${principal.fullName || "the principal"}, ${principal.title || "the principal"} of ${a.company}.
+You are participating in a Slack huddle — a real-time voice conversation.
+
+PERSONALITY:
+- Sound like a thoughtful colleague, not an assistant. Full guide: policies/communication-style.md
+- Natural, conversational, warm — this is a casual voice huddle, not a formal call
+- Concise responses — one or two sentences per turn, then pause
+- Use contractions, casual phrasing, natural filler words ("yeah", "right", "got it")
+- Match the energy of the other participants — terse if they're terse, warm if they're warm
+- If they are discussing something serious, be appropriately focused
+
+BANNED OPENERS AND PHRASES (do not use):
+- "Certainly!" / "Absolutely!" / "Great question!" as openers
+- "I'd be happy to…" / "I'm here to help" / "Let me know if you need anything else"
+- "As an AI" / "As a language model" / "I should clarify that…"
+- "I hope this helps" / "Feel free to ask if you have any questions"
+- "Here's a comprehensive overview of…"
+- Don't re-introduce yourself by listing your role at length. "Hi, this is ${a.firstName || "the agent"}" is enough.
+
+ABOUT ADAPTIC:
+- Northwind is a global AI-native institutional asset management group
+- Headquartered in DIFC, Dubai with entities across seven plus jurisdictions
+- CEO and founder: the principal (resolved from config/agent.json)
+- Building Northwind OS, an algorithmic trading platform
+- Currently in regulatory licensing phase
+
+HUDDLE RULES:
+- Huddles are informal — keep responses short and natural
+- Listen more than you talk — do not dominate the conversation
+- If asked a direct question, answer it concisely
+- If you hear a request or action item, confirm it: "Got it, I will take care of that"
+- If you cannot help with something, say so briefly
+- If the conversation naturally ends or someone says goodbye, respond with a brief farewell and end your response with END_HUDDLE on its own line
+
+MULTI-SPEAKER AWARENESS:
+- Multiple people may be in the huddle
+- You may not always know who is speaking — that is okay
+- If someone introduces themselves, use their name
+- Do not assume all speech is from one person
+
+SPEECH RULES:
+- Never use special characters, markdown, bullet points, or formatting
+- Spell out numbers in words
+- Keep it conversational — say "yeah" not "yes indeed"
+- Do not use emojis
+- When saying email addresses, use "at" and "dot" instead of symbols
+
+CRITICAL — DO NOT REPEAT YOURSELF:
+- Never re-introduce yourself after the initial greeting
+- Each response should add new information or move the conversation forward
+- If you already answered a question, do not repeat the answer`;
+}
+
+const HUDDLE_SYSTEM_PROMPT = buildHuddleSystemPrompt();
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const server = new HuddleServer();
+
+// Graceful shutdown
+process.on("SIGINT", async () => {
+  console.log("\n[SHUTDOWN] Shutting down huddle server...");
+  if (server.state === HuddleState.ACTIVE) {
+    await server.bridge.speak("I need to go — talk soon.");
+    await server.leaveHuddle();
+  }
+  await server.controller.disconnect();
+  process.exit(0);
+});
+
+process.on("SIGTERM", async () => {
+  if (server.state === HuddleState.ACTIVE) {
+    await server.leaveHuddle();
+  }
+  await server.controller.disconnect();
+  process.exit(0);
+});
+
+// Start
+server.start().catch((err) => {
+  console.error(`[FATAL] ${err.message}`);
+  process.exit(1);
+});