@adaptic/maestro 1.0.0

package/scripts/huddle/huddle-controller.mjs

@@ -0,0 +1,942 @@
+#!/usr/bin/env node
+/**
+ * Sophie Huddle — Controller
+ *
+ * Controls the Slack desktop app via Chrome DevTools Protocol for huddle
+ * participation. Connects to Slack launched with --remote-debugging-port
+ * and automates join/initiate/leave via keyboard shortcuts and DOM observation.
+ *
+ * Architecture:
+ *   Slack Desktop (Electron) ←→ CDP (port 9222) ←→ This controller
+ *
+ * Primary automation method: keyboard shortcuts (most stable across updates)
+ *   - Cmd+K         → Quick switcher (navigate to channel/DM)
+ *   - Cmd+Shift+H   → Toggle huddle (start/join/leave)
+ *
+ * Fallback: DOM queries via CDP for state verification and invitation detection.
+ */
+
+import { EventEmitter } from "node:events";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { WebSocket } from "ws";
+
+const execFileAsync = promisify(execFile);
+
+const CDP_URL = process.env.CDP_URL || "http://localhost:9222";
+const RECONNECT_INTERVAL_MS = 5000;
+const POLL_INTERVAL_MS = 2000;
+
+/**
+ * HuddleController manages Slack huddle interactions via CDP.
+ *
+ * Events emitted:
+ *   - 'connected'     — CDP connection established
+ *   - 'disconnected'  — CDP connection lost
+ *   - 'huddle:invitation' — Incoming huddle invitation detected { channel, from }
+ *   - 'huddle:joined'     — Successfully joined a huddle { channel }
+ *   - 'huddle:left'       — Left a huddle
+ *   - 'huddle:started'    — Initiated a new huddle { channel }
+ *   - 'huddle:participant_joined'  — Someone joined the huddle { name }
+ *   - 'huddle:participant_left'    — Someone left the huddle { name }
+ *   - 'error'         — An error occurred { message, detail }
+ */
+export class HuddleController extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.cdpUrl = options.cdpUrl || CDP_URL;
+    this.ws = null;
+    this.messageId = 0;
+    this.pendingMessages = new Map(); // id → { resolve, reject, timer }
+    this.targetId = null;
+    this.sessionId = null;
+    this.connected = false;
+    this.huddleActive = false;
+    this.currentChannel = null;
+    this.pollTimer = null;
+    this.reconnectTimer = null;
+  }
+
+  // -------------------------------------------------------------------------
+  // Connection lifecycle
+  // -------------------------------------------------------------------------
+
+  /**
+   * Connect to Slack's CDP endpoint. Finds the main Slack window target
+   * and establishes a debugging session.
+   */
+  async connect() {
+    try {
+      // Discover debuggable targets
+      const targets = await this._fetchTargets();
+      if (!targets || targets.length === 0) {
+        throw new Error("No CDP targets found — is Slack running with --remote-debugging-port?");
+      }
+
+      // Find the main Slack client page (app.slack.com), not the blank huddle preview
+      const slackTarget =
+        targets.find(
+          (t) => t.type === "page" && t.url && t.url.includes("app.slack.com")
+        ) ||
+        targets.find(
+          (t) =>
+            t.type === "page" &&
+            t.url &&
+            !t.url.startsWith("devtools://") &&
+            t.url !== "about:blank"
+        );
+
+      if (!slackTarget) {
+        throw new Error("No Slack page target found among CDP targets");
+      }
+
+      this.targetId = slackTarget.id;
+
+      // Connect WebSocket to the target
+      const wsUrl = slackTarget.webSocketDebuggerUrl;
+      if (!wsUrl) {
+        throw new Error("Target has no webSocketDebuggerUrl");
+      }
+
+      await this._connectWebSocket(wsUrl);
+      this.connected = true;
+      this.emit("connected");
+
+      // Start polling for huddle state
+      this._startPolling();
+
+      return true;
+    } catch (err) {
+      this.emit("error", { message: "Connection failed", detail: err.message });
+      this._scheduleReconnect();
+      return false;
+    }
+  }
+
+  /**
+   * Disconnect from CDP and clean up.
+   */
+  async disconnect() {
+    this._stopPolling();
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+
+    this.connected = false;
+    this.pendingMessages.clear();
+    this.emit("disconnected");
+  }
+
+  // -------------------------------------------------------------------------
+  // Huddle actions
+  // -------------------------------------------------------------------------
+
+  /**
+   * Navigate to a channel or DM by name using Cmd+K quick switcher.
+   * @param {string} name - Channel name (e.g., "#general") or person name
+   * @returns {Promise<boolean>} Whether navigation succeeded
+   */
+  async navigateToChannel(name) {
+    if (!this.connected) throw new Error("Not connected to Slack");
+
+    // Use system-level keystrokes — Cmd+K is an Electron accelerator,
+    // not a DOM event, so CDP Input.dispatchKeyEvent doesn't trigger it.
+    await this._systemKeystroke("k");
+    await this._sleep(800);
+
+    // Type the person/channel name into the quick switcher
+    await this._systemType(name);
+    await this._sleep(1200);
+
+    // Press Enter to navigate to the selected result
+    await this._systemKeyPress("return");
+    await this._sleep(1500);
+
+    this.currentChannel = name;
+    return true;
+  }
+
+  /**
+   * Join an active huddle or start a new one in the current channel.
+   * Uses Cmd+Shift+H keyboard shortcut.
+   * @param {string} [channel] - Optional channel to navigate to first
+   * @returns {Promise<boolean>}
+   */
+  async joinHuddle(channel) {
+    if (!this.connected) throw new Error("Not connected to Slack");
+
+    if (channel) {
+      await this.navigateToChannel(channel);
+    }
+
+    // Step 1: Click huddle button (opens preview window)
+    const previewOpened = await this._clickHuddleButton();
+    if (!previewOpened) {
+      await this._systemKeystroke("h", ["command", "shift"]);
+    }
+    await this._sleep(2000);
+
+    // Step 2: Click "Start huddle" in preview window
+    await this._clickPreviewStartButton();
+    await this._sleep(4000);
+
+    // Verify huddle state
+    const inHuddle = await this._checkHuddleActive();
+    if (inHuddle) {
+      this.huddleActive = true;
+      this.emit("huddle:joined", { channel: channel || this.currentChannel });
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Initiate a new huddle in a specific channel or DM.
+   * @param {string} channel - Channel name or person name
+   * @returns {Promise<boolean>}
+   */
+  async initiateHuddle(channel) {
+    if (!this.connected) throw new Error("Not connected to Slack");
+
+    await this.navigateToChannel(channel);
+    await this._sleep(500);
+
+    // Step 1: Click the huddle start button in the main window via React props.
+    // Slack opens a "Huddle preview" window where the user confirms mic/video
+    // before actually joining. We invoke the React onClick handler because
+    // CDP mouse events and DOM .click() are silently ignored by Slack's
+    // Electron security model.
+    const previewOpened = await this._clickHuddleButton();
+    if (!previewOpened) {
+      // Fallback: try Cmd+Shift+H keyboard shortcut
+      await this._systemKeystroke("h", ["command", "shift"]);
+    }
+    await this._sleep(2000);
+
+    // Step 2: Click "Start huddle" in the preview window using cliclick
+    // (system-level mouse click). The preview window is the first Slack
+    // window in the process list. We use the preview window's screen
+    // position to calculate absolute coordinates.
+    const started = await this._clickPreviewStartButton();
+    if (!started) {
+      console.warn("[HUDDLE] Failed to click Start in preview window");
+    }
+    await this._sleep(4000);
+
+    // Verify huddle is active
+    const inHuddle = await this._checkHuddleActive();
+    if (inHuddle) {
+      this.huddleActive = true;
+      this.emit("huddle:started", { channel });
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Click the huddle button in the main window via React onClick handler.
+   * This opens the huddle preview window.
+   * @returns {Promise<boolean>}
+   */
+  async _clickHuddleButton() {
+    try {
+      return await this._evaluate(`
+        (() => {
+          const btn = document.querySelector("[data-qa='huddle_channel_header_button__start_button']");
+          if (!btn) return false;
+          const propsKey = Object.keys(btn).find(k => k.startsWith('__reactProps'));
+          if (propsKey && btn[propsKey] && btn[propsKey].onClick) {
+            btn[propsKey].onClick({
+              target: btn, currentTarget: btn,
+              nativeEvent: new MouseEvent('click', {bubbles: true}),
+              type: 'click', preventDefault: () => {}, stopPropagation: () => {}, persist: () => {}
+            });
+            return true;
+          }
+          btn.click();
+          return true;
+        })()
+      `);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Click "Start huddle" in the Huddle preview window using system-level
+   * mouse click. Discovers the preview window position via AppleScript
+   * and the button position via CDP on the preview renderer target.
+   * @returns {Promise<boolean>}
+   */
+  async _clickPreviewStartButton() {
+    try {
+      // Get preview window position via AppleScript
+      const { stdout: windowInfo } = await execFileAsync("osascript", ["-e", `
+        tell application "System Events"
+          tell process "Slack"
+            repeat with i from 1 to (count of windows)
+              set w to window i
+              if name of w contains "Huddle preview" or name of w contains "Huddle:" then
+                set p to position of w
+                return (item 1 of p as text) & "," & (item 2 of p as text)
+              end if
+            end repeat
+            return "not_found"
+          end tell
+        end tell
+      `]);
+
+      const pos = windowInfo.trim();
+      if (pos === "not_found") {
+        console.warn("[HUDDLE] Preview window not found");
+        return false;
+      }
+
+      const [winX, winY] = pos.split(",").map(Number);
+
+      // Get button position in the preview window via CDP
+      // Find the preview renderer target
+      const targets = await this._fetchTargets();
+      const previewTarget = targets.find(t =>
+        t.title && t.title.includes("Huddle") && t.type === "page"
+      );
+
+      if (!previewTarget) {
+        console.warn("[HUDDLE] Preview CDP target not found");
+        // Fallback: use known default position (center-bottom of preview)
+        const screenX = winX + 316;
+        const screenY = winY + 974;
+        await execFileAsync("cliclick", [`c:${screenX},${screenY}`]);
+        return true;
+      }
+
+      // Connect to preview target to find button position
+      const btnPos = await this._getPreviewButtonPosition(previewTarget.webSocketDebuggerUrl);
+      if (!btnPos) {
+        // Fallback to default position
+        const screenX = winX + 316;
+        const screenY = winY + 974;
+        await execFileAsync("cliclick", [`c:${screenX},${screenY}`]);
+        return true;
+      }
+
+      const screenX = winX + Math.round(btnPos.x);
+      const screenY = winY + Math.round(btnPos.y);
+      console.log(`[HUDDLE] Clicking Start at screen (${screenX}, ${screenY})`);
+      await execFileAsync("cliclick", [`c:${screenX},${screenY}`]);
+      return true;
+    } catch (err) {
+      console.error(`[HUDDLE] Preview click error: ${err.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * Connect to the huddle preview CDP target and find the Start button position.
+   * @param {string} wsUrl - WebSocket debugger URL for the preview target
+   * @returns {Promise<{x: number, y: number}|null>}
+   */
+  async _getPreviewButtonPosition(wsUrl) {
+    return new Promise((resolve) => {
+      const previewWs = new WebSocket(wsUrl);
+      const timeout = setTimeout(() => { previewWs.close(); resolve(null); }, 5000);
+
+      previewWs.on("open", () => {
+        previewWs.send(JSON.stringify({
+          id: 1,
+          method: "Runtime.evaluate",
+          params: {
+            expression: `(() => {
+              const btn = document.querySelector("[data-qa='huddle_invite_window_with_preview_content_join_button']");
+              if (!btn) return null;
+              const rect = btn.getBoundingClientRect();
+              return { x: rect.x + rect.width/2, y: rect.y + rect.height/2 };
+            })()`,
+            returnByValue: true,
+          },
+        }));
+      });
+
+      previewWs.on("message", (data) => {
+        const msg = JSON.parse(data.toString());
+        if (msg.id === 1) {
+          clearTimeout(timeout);
+          previewWs.close();
+          resolve(msg.result?.result?.value || null);
+        }
+      });
+
+      previewWs.on("error", () => { clearTimeout(timeout); resolve(null); });
+    });
+  }
+
+  /**
+   * Leave the current huddle.
+   * @returns {Promise<boolean>}
+   */
+  async leaveHuddle() {
+    if (!this.connected) throw new Error("Not connected to Slack");
+    if (!this.huddleActive) return true; // Already not in a huddle
+
+    // Toggle huddle off via system-level Cmd+Shift+H
+    await this._systemKeystroke("h", ["command", "shift"]);
+    await this._sleep(2000);
+
+    const stillActive = await this._checkHuddleActive();
+    if (!stillActive) {
+      this.huddleActive = false;
+      this.emit("huddle:left");
+      return true;
+    }
+
+    // Fallback: try clicking the Leave button via DOM
+    try {
+      await this._clickLeaveButton();
+      await this._sleep(1000);
+      this.huddleActive = false;
+      this.emit("huddle:left");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Accept an incoming huddle invitation by clicking the Join button.
+   * @returns {Promise<boolean>}
+   */
+  async acceptInvitation() {
+    if (!this.connected) throw new Error("Not connected to Slack");
+
+    // Try to find and click the Join button in the invitation popup
+    const clicked = await this._clickJoinButton();
+    if (clicked) {
+      await this._sleep(2000);
+      this.huddleActive = true;
+      this.emit("huddle:joined", { channel: this.currentChannel });
+      return true;
+    }
+
+    // Fallback: use keyboard shortcut
+    return this.joinHuddle();
+  }
+
+  /**
+   * Mute/unmute Sophie's microphone in the huddle.
+   * @param {boolean} muted - true to mute, false to unmute
+   */
+  async setMute(muted) {
+    if (!this.connected || !this.huddleActive) return;
+
+    // Slack huddle mute shortcut: M key when huddle is focused
+    // Or use the mute button via DOM
+    const currentlyMuted = await this._checkMuteState();
+    if (currentlyMuted !== muted) {
+      await this._sendKey("m");
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // State observation
+  // -------------------------------------------------------------------------
+
+  /**
+   * Check if Sophie is currently in a huddle.
+   * @returns {Promise<boolean>}
+   */
+  async isInHuddle() {
+    if (!this.connected) return false;
+    return this._checkHuddleActive();
+  }
+
+  /**
+   * Get current huddle participants.
+   * @returns {Promise<string[]>} List of participant display names
+   */
+  async getParticipants() {
+    if (!this.connected || !this.huddleActive) return [];
+
+    try {
+      const result = await this._evaluate(`
+        (() => {
+          // Look for participant avatars/names in the huddle UI
+          const participantEls = document.querySelectorAll(
+            '[data-qa="huddle-participant-name"], ' +
+            '[class*="huddle"] [class*="participant"] [class*="name"], ' +
+            '[class*="huddle"] [class*="avatar"][aria-label]'
+          );
+          return Array.from(participantEls).map(el =>
+            el.textContent?.trim() || el.getAttribute('aria-label') || ''
+          ).filter(Boolean);
+        })()
+      `);
+      return result || [];
+    } catch {
+      return [];
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // CDP communication internals
+  // -------------------------------------------------------------------------
+
+  async _fetchTargets() {
+    const resp = await fetch(`${this.cdpUrl}/json`);
+    if (!resp.ok) throw new Error(`CDP /json returned ${resp.status}`);
+    return resp.json();
+  }
+
+  _connectWebSocket(url) {
+    return new Promise((resolve, reject) => {
+      this.ws = new WebSocket(url);
+
+      this.ws.onopen = () => resolve();
+      this.ws.onerror = (err) => reject(err);
+
+      this.ws.onmessage = (event) => {
+        try {
+          const msg = JSON.parse(typeof event.data === "string" ? event.data : event.data.toString());
+
+          // Handle response to a pending message
+          if (msg.id !== undefined && this.pendingMessages.has(msg.id)) {
+            const { resolve, reject, timer } = this.pendingMessages.get(msg.id);
+            this.pendingMessages.delete(msg.id);
+            clearTimeout(timer);
+
+            if (msg.error) {
+              reject(new Error(msg.error.message));
+            } else {
+              resolve(msg.result);
+            }
+          }
+        } catch (err) {
+          // Ignore parse errors from CDP events we don't care about
+        }
+      };
+
+      this.ws.onclose = () => {
+        this.connected = false;
+        this.emit("disconnected");
+        this._scheduleReconnect();
+      };
+    });
+  }
+
+  /**
+   * Send a CDP command and wait for its response.
+   * @param {string} method - CDP method (e.g., "Runtime.evaluate")
+   * @param {object} params - CDP method parameters
+   * @param {number} timeoutMs - Response timeout
+   * @returns {Promise<any>} CDP response result
+   */
+  _sendCommand(method, params = {}, timeoutMs = 10000) {
+    return new Promise((resolve, reject) => {
+      if (!this.ws || this.ws.readyState !== 1) {
+        return reject(new Error("WebSocket not connected"));
+      }
+
+      const id = ++this.messageId;
+      const timer = setTimeout(() => {
+        this.pendingMessages.delete(id);
+        reject(new Error(`CDP command ${method} timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+
+      this.pendingMessages.set(id, { resolve, reject, timer });
+      this.ws.send(JSON.stringify({ id, method, params }));
+    });
+  }
+
+  /**
+   * Evaluate JavaScript in the Slack renderer context.
+   */
+  async _evaluate(expression) {
+    const result = await this._sendCommand("Runtime.evaluate", {
+      expression,
+      returnByValue: true,
+      awaitPromise: true,
+    });
+    return result?.result?.value;
+  }
+
+  // -------------------------------------------------------------------------
+  // System-level keyboard (via AppleScript)
+  //
+  // Slack's Cmd+K and Cmd+Shift+H are Electron menu accelerators, not DOM
+  // keyboard events. CDP's Input.dispatchKeyEvent only fires DOM events, so
+  // these shortcuts don't trigger. We use AppleScript to send system-level
+  // keystrokes directly to the Slack process.
+  // -------------------------------------------------------------------------
+
+  /**
+   * Bring Slack to front and send a system-level keystroke via AppleScript.
+   * @param {string} key - The key character (e.g., "k", "h")
+   * @param {string[]} modifiers - e.g. ["command"], ["command", "shift"]
+   */
+  async _systemKeystroke(key, modifiers = ["command"]) {
+    const using = modifiers.map((m) => `${m} down`).join(", ");
+    const script = `
+      tell application "Slack" to activate
+      delay 0.3
+      tell application "System Events"
+        keystroke "${key}" using {${using}}
+      end tell
+    `;
+    await execFileAsync("osascript", ["-e", script]);
+  }
+
+  /**
+   * Type text into the frontmost app via AppleScript (for quick switcher input).
+   * @param {string} text
+   */
+  async _systemType(text) {
+    // Escape special chars for AppleScript string
+    const escaped = text.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    const script = `
+      tell application "System Events"
+        keystroke "${escaped}"
+      end tell
+    `;
+    await execFileAsync("osascript", ["-e", script]);
+  }
+
+  /**
+   * Send a single key (Enter, Escape, etc.) via AppleScript.
+   * @param {string} keyName - e.g., "return", "escape", "tab"
+   */
+  async _systemKeyPress(keyName) {
+    const script = `
+      tell application "System Events"
+        key code ${keyName === "return" ? 36 : keyName === "escape" ? 53 : keyName === "tab" ? 48 : 0}
+      end tell
+    `;
+    await execFileAsync("osascript", ["-e", script]);
+  }
+
+  // -------------------------------------------------------------------------
+  // CDP-level keyboard / input helpers (for DOM interactions)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Send a keyboard shortcut (e.g., Cmd+K, Cmd+Shift+H).
+   */
+  async _sendKeyCombo(key, modifiers = []) {
+    const keyCode = key.toUpperCase().charCodeAt(0);
+    const modFlag =
+      (modifiers.includes("Alt") ? 1 : 0) |
+      (modifiers.includes("Control") ? 2 : 0) |
+      (modifiers.includes("Meta") ? 4 : 0) |
+      (modifiers.includes("Shift") ? 8 : 0);
+
+    // Key down with modifiers
+    await this._sendCommand("Input.dispatchKeyEvent", {
+      type: "keyDown",
+      key,
+      code: `Key${key.toUpperCase()}`,
+      windowsVirtualKeyCode: keyCode,
+      nativeVirtualKeyCode: keyCode,
+      modifiers: modFlag,
+    });
+
+    // Small delay
+    await this._sleep(50);
+
+    // Key up
+    await this._sendCommand("Input.dispatchKeyEvent", {
+      type: "keyUp",
+      key,
+      code: `Key${key.toUpperCase()}`,
+      windowsVirtualKeyCode: keyCode,
+      nativeVirtualKeyCode: keyCode,
+      modifiers: modFlag,
+    });
+  }
+
+  async _sendKey(key) {
+    const keyMap = {
+      Enter: { code: "Enter", keyCode: 13 },
+      Escape: { code: "Escape", keyCode: 27 },
+      Tab: { code: "Tab", keyCode: 9 },
+    };
+
+    const mapped = keyMap[key] || { code: `Key${key.toUpperCase()}`, keyCode: key.toUpperCase().charCodeAt(0) };
+
+    await this._sendCommand("Input.dispatchKeyEvent", {
+      type: "keyDown",
+      key,
+      code: mapped.code,
+      windowsVirtualKeyCode: mapped.keyCode,
+      nativeVirtualKeyCode: mapped.keyCode,
+    });
+    await this._sleep(50);
+    await this._sendCommand("Input.dispatchKeyEvent", {
+      type: "keyUp",
+      key,
+      code: mapped.code,
+      windowsVirtualKeyCode: mapped.keyCode,
+      nativeVirtualKeyCode: mapped.keyCode,
+    });
+  }
+
+  async _typeText(text) {
+    for (const char of text) {
+      await this._sendCommand("Input.dispatchKeyEvent", {
+        type: "keyDown",
+        key: char,
+        text: char,
+      });
+      await this._sendCommand("Input.dispatchKeyEvent", {
+        type: "keyUp",
+        key: char,
+      });
+      await this._sleep(30); // Realistic typing speed
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // DOM queries for huddle state
+  // -------------------------------------------------------------------------
+
+  async _checkHuddleActive() {
+    try {
+      // Check main window DOM for huddle indicators
+      const mainActive = await this._evaluate(`
+        (() => {
+          // Primary: huddle workspace dialog has children when active
+          const workspace = document.querySelector('div.p-huddle_workspace[role="dialog"]');
+          if (workspace && workspace.children.length > 0) return true;
+
+          // Fallback: look for leave/end buttons
+          const leaveBtn = document.querySelector(
+            '[aria-label*="Leave huddle"], [aria-label*="End huddle"], ' +
+            '[data-qa*="huddle"][data-qa*="leave"], [data-qa*="huddle"][data-qa*="end"]'
+          );
+          if (leaveBtn) return true;
+
+          // Fallback: audio element is actively playing
+          const activeAudio = [...document.querySelectorAll('audio')].some(a => !a.paused);
+          if (activeAudio) return true;
+
+          // Fallback: title contains 🔊 (active audio indicator)
+          if (document.title.includes('🔊')) return true;
+
+          return false;
+        })()
+      `);
+      if (mainActive) return true;
+
+      // Check preview window for active huddle UI (the "Leave" button
+      // only appears in the preview window once the huddle has started)
+      try {
+        const targets = await this._fetchTargets();
+        const previewTarget = targets.find(t =>
+          t.title && (t.title.includes("Huddle:") || t.title.includes("🎤")) && t.type === "page"
+        );
+        if (previewTarget) return true;
+      } catch { /* optional check */ }
+
+      return false;
+    } catch {
+      return false;
+    }
+  }
+
+  async _checkMuteState() {
+    try {
+      // Mute button appears inside p-huddle_workspace when huddle is active
+      return await this._evaluate(`
+        (() => {
+          const muteBtn = document.querySelector(
+            '.p-huddle_workspace [aria-label*="Mute"], ' +
+            '.p-huddle_workspace [aria-label*="mute"], ' +
+            '[data-qa*="huddle"][data-qa*="mute"]'
+          );
+          if (!muteBtn) return null;
+          return muteBtn.getAttribute('aria-pressed') === 'true' ||
+                 muteBtn.getAttribute('aria-label')?.toLowerCase().includes('unmute');
+        })()
+      `);
+    } catch {
+      return null;
+    }
+  }
+
+  async _clickJoinButton() {
+    try {
+      // Verified: the start/join button has data-qa="huddle_channel_header_button__start_button"
+      // and aria-label="Start huddle in {channel}" (changes to "Join" when active)
+      return await this._evaluate(`
+        (() => {
+          // Primary: the huddle start/join button in channel header
+          const startBtn = document.querySelector(
+            '[data-qa="huddle_channel_header_button__start_button"]'
+          );
+          if (startBtn) { startBtn.click(); return true; }
+
+          // Fallback: any button with "Join" text in a huddle context
+          const joinBtns = [...document.querySelectorAll('button, [role="button"]')].filter(el => {
+            const text = (el.textContent || '').trim().toLowerCase();
+            const label = (el.getAttribute('aria-label') || '').toLowerCase();
+            return text === 'join' || label.includes('join huddle') || label.includes('join this huddle');
+          });
+          if (joinBtns.length > 0) { joinBtns[0].click(); return true; }
+
+          return false;
+        })()
+      `);
+    } catch {
+      return false;
+    }
+  }
+
+  async _clickLeaveButton() {
+    try {
+      return await this._evaluate(`
+        (() => {
+          // Look inside the huddle workspace dialog for leave/end buttons
+          const workspace = document.querySelector('.p-huddle_workspace');
+          const scope = workspace || document;
+
+          const leaveBtns = [...scope.querySelectorAll('button, [role="button"]')].filter(el => {
+            const text = (el.textContent || '').trim().toLowerCase();
+            const label = (el.getAttribute('aria-label') || '').toLowerCase();
+            const qa = (el.getAttribute('data-qa') || '').toLowerCase();
+            return text === 'leave' || label.includes('leave huddle') ||
+                   label.includes('end huddle') || qa.includes('leave') || qa.includes('end');
+          });
+          if (leaveBtns.length > 0) { leaveBtns[0].click(); return true; }
+          return false;
+        })()
+      `);
+    } catch {
+      return false;
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Huddle invitation detection (polling)
+  // -------------------------------------------------------------------------
+
+  _startPolling() {
+    this._stopPolling();
+    this.pollTimer = setInterval(() => this._pollHuddleState(), POLL_INTERVAL_MS);
+  }
+
+  _stopPolling() {
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+  }
+
+  async _pollHuddleState() {
+    if (!this.connected) return;
+
+    try {
+      // Check for incoming huddle invitation popup or active huddle indicator
+      const invitation = await this._evaluate(`
+        (() => {
+          // Method 1: huddle workspace dialog became populated (someone started a huddle)
+          const workspace = document.querySelector('div.p-huddle_workspace[role="dialog"]');
+          if (workspace && workspace.children.length > 0) {
+            // Extract participant info from the huddle workspace
+            const nameEl = workspace.querySelector(
+              '[class*="name"], [class*="caller"], [class*="participant"]'
+            );
+            return {
+              from: nameEl?.textContent?.trim() || 'Someone',
+              channel: 'active-huddle',
+            };
+          }
+
+          // Method 2: Incoming notification/toast for huddle invitation
+          const toasts = document.querySelectorAll(
+            '[class*="huddle"][class*="incoming"], ' +
+            '[class*="huddle"][class*="invitation"], ' +
+            '[class*="huddle"][class*="ringing"], ' +
+            '[class*="huddle_notification"]'
+          );
+          for (const toast of toasts) {
+            const nameEl = toast.querySelector('[class*="name"], [class*="title"]');
+            const channelEl = toast.querySelector('[class*="channel"], [class*="subtitle"]');
+            return {
+              from: nameEl?.textContent?.trim() || 'Unknown',
+              channel: channelEl?.textContent?.trim() || 'Unknown',
+            };
+          }
+
+          // Method 3: The start button label changed to indicate an active huddle
+          const startBtn = document.querySelector('[data-qa="huddle_channel_header_button__start_button"]');
+          if (startBtn) {
+            const label = startBtn.getAttribute('aria-label') || '';
+            if (label.toLowerCase().includes('join')) {
+              // Button says "Join huddle" instead of "Start huddle" — someone is in a huddle
+              const channelBtn = document.querySelector('[data-qa="channel_name_button"]');
+              return {
+                from: 'Active huddle',
+                channel: channelBtn?.textContent?.trim() || 'current channel',
+              };
+            }
+          }
+
+          return null;
+        })()
+      `);
+
+      if (invitation && !this.huddleActive) {
+        this.emit("huddle:invitation", invitation);
+      }
+
+      // Track huddle state transitions
+      const isActive = await this._checkHuddleActive();
+      if (isActive && !this.huddleActive) {
+        this.huddleActive = true;
+        this.emit("huddle:joined", { channel: this.currentChannel || "active-huddle" });
+      } else if (!isActive && this.huddleActive) {
+        // The main window DOM is unreliable for detecting huddle end because
+        // the huddle UI runs in a separate Electron window. Only mark as left
+        // after multiple consecutive "not active" checks to avoid false alarms.
+        if (!this._leaveCheckCount) this._leaveCheckCount = 0;
+        this._leaveCheckCount++;
+        if (this._leaveCheckCount >= 5) { // 5 polls × 2s = 10 seconds of inactivity
+          this.huddleActive = false;
+          this._leaveCheckCount = 0;
+          this.emit("huddle:left");
+        }
+      } else {
+        this._leaveCheckCount = 0;
+      }
+    } catch {
+      // Polling errors are non-fatal
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Reconnection
+  // -------------------------------------------------------------------------
+
+  _scheduleReconnect() {
+    if (this.reconnectTimer) return;
+    this.reconnectTimer = setTimeout(async () => {
+      this.reconnectTimer = null;
+      await this.connect();
+    }, RECONNECT_INTERVAL_MS);
+  }
+
+  // -------------------------------------------------------------------------
+  // Utilities
+  // -------------------------------------------------------------------------
+
+  _sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+export default HuddleController;