Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

17.1 KB
Raw Blame
"""Who and where the chat bots can reach, by name, for the People and
department pickers (``GET /chat-directory/*``, ``api/routes/chat_directory.py``).

So nobody has to copy a raw Slack, Discord or Telegram id by hand, this lists
from the bots this instance runs:

- **Slack** (``SLACK_BOT_TOKEN``): channels from ``conversations.list``
  (public ones and the private ones the bot is in; scopes ``channels:read``,
  ``groups:read``) and people from ``users.list`` (no bots, no deactivated
  accounts; ``users:read``, plus ``users:read.email`` for their profile
  email). ``slack_user_by_email`` finds one person by work email
  (``users.lookupByEmail``).
- **Discord** (``DISCORD_BOT_TOKEN``): text and announcement channels of the
  servers the bot is in (only ``DISCORD_GUILD_IDS`` when set), and their
  members. Listing members needs the Server Members privileged intent; when
  Discord refuses, the members list is empty with ``members_available`` false
  rather than an error.
- **Telegram** (``TELEGRAM_BOT_TOKEN``): Telegram cannot list chats, so this
  reads the ones the bot has seen (``integrations.telegram_chats``): private
  chats are people, groups are rooms.

Each list is cached in-process for ``CACHE_TTL_S`` seconds and capped at
``MAX_ITEMS``. A provider with no token reads as ``configured=False`` with no
options; a provider that fails reads as ``ok=False`` with no options. Tokens
never leave this module: they go only in the Authorization header to the
provider's own API host.
"""
from __future__ import annotations

import asyncio
import logging
import time
from collections.abc import Awaitable, Callable
from datetime import datetime
from typing import Any, Literal

import httpx
from pydantic import BaseModel, ConfigDict, Field

from openexecutive.config import get_settings

logger = logging.getLogger(__name__)

CACHE_TTL_S = 60.0
MAX_ITEMS = 2000
_PAGE = 200
_MAX_PAGES = MAX_ITEMS // _PAGE
_TIMEOUT_S = 10.0

SLACK_API = "https://slack.com/api/"
DISCORD_API = "https://discord.com/api/v10"

# Discord channel types the Executive can post to: text and announcement.
_DISCORD_TEXT_TYPES = frozenset({0, 5})

Provider = Literal["slack", "discord", "telegram"]
Kind = Literal["people", "channels"]


class DirectoryOption(BaseModel):
    """One pickable person or room. ``id`` is what gets saved; ``name`` and
    ``detail`` are what the picker shows."""

    model_config = ConfigDict(frozen=True)

    id: str
    name: str
    detail: str = ""
    email: str | None = None


class ProviderList(BaseModel):
    configured: bool
    ok: bool = True
    options: list[DirectoryOption] = Field(default_factory=list)
    truncated: bool = False
    # Discord people only: False when Discord refused to list members (the
    # Server Members intent is off). None elsewhere.
    members_available: bool | None = None


class DirectoryListing(BaseModel):
    slack: ProviderList
    discord: ProviderList
    telegram: ProviderList


class SlackMatch(BaseModel):
    configured: bool
    match: DirectoryOption | None = None


# --------------------------------------------------------------------------- #
# Cache
# --------------------------------------------------------------------------- #

_cache: dict[tuple[str, str], tuple[float, ProviderList]] = {}
_locks: dict[tuple[str, str], asyncio.Lock] = {}

# Tests swap this for a client on an ``httpx.MockTransport``.
ClientFactory = Callable[[], httpx.AsyncClient]


def _default_client() -> httpx.AsyncClient:
    return httpx.AsyncClient(timeout=_TIMEOUT_S)


client_factory: ClientFactory = _default_client


def clear_cache() -> None:
    _cache.clear()
    _locks.clear()


async def _cached(
    key: tuple[str, str], load: Callable[[], Awaitable[ProviderList]]
) -> ProviderList:
    hit = _cache.get(key)
    if hit is not None and time.monotonic() - hit[0] < CACHE_TTL_S:
        return hit[1]
    lock = _locks.setdefault(key, asyncio.Lock())
    async with lock:
        hit = _cache.get(key)
        if hit is not None and time.monotonic() - hit[0] < CACHE_TTL_S:
            return hit[1]
        result = await load()
        _cache[key] = (time.monotonic(), result)
        return result


# --------------------------------------------------------------------------- #
# Slack
# --------------------------------------------------------------------------- #

class _SlackError(Exception):
    pass


async def _slack_call(
    client: httpx.AsyncClient, token: str, method: str, params: dict[str, Any]
) -> dict[str, Any]:
    resp = await client.get(
        SLACK_API + method, params=params, headers={"Authorization": f"Bearer {token}"}
    )
    if resp.status_code == 429:
        raise _SlackError("rate_limited")
    resp.raise_for_status()
    data = resp.json()
    if not isinstance(data, dict):
        raise _SlackError("bad_response")
    if not data.get("ok"):
        raise _SlackError(str(data.get("error") or "not_ok"))
    return data


async def _slack_paged(
    token: str, method: str, params: dict[str, Any], items_key: str
) -> tuple[list[dict[str, Any]], bool]:
    """All pages of a cursor-paginated Slack list, up to ``_MAX_PAGES``.
    Returns (items, truncated). A failure after the first page keeps what
    was read and marks it truncated."""
    items: list[dict[str, Any]] = []
    cursor = ""
    async with client_factory() as client:
        for page in range(_MAX_PAGES):
            query = {**params, "limit": _PAGE}
            if cursor:
                query["cursor"] = cursor
            try:
                data = await _slack_call(client, token, method, query)
            except (_SlackError, httpx.HTTPError):
                if page == 0:
                    raise
                return items, True
            items.extend(x for x in data.get(items_key) or [] if isinstance(x, dict))
            cursor = str((data.get("response_metadata") or {}).get("next_cursor") or "")
            if not cursor:
                return items, False
    return items, True


def _slack_person(user: dict[str, Any]) -> DirectoryOption | None:
    uid = user.get("id")
    if (
        not isinstance(uid, str)
        or not uid
        or uid == "USLACKBOT"
        or user.get("deleted")
        or user.get("is_bot")
        or user.get("is_app_user")
    ):
        return None
    profile = user.get("profile") or {}
    handle = str(profile.get("display_name") or user.get("name") or "").strip()
    name = str(profile.get("real_name") or user.get("real_name") or handle or uid).strip()
    email = profile.get("email")
    return DirectoryOption(
        id=uid,
        name=name,
        detail=f"@{handle}" if handle else "",
        email=email.strip().lower() if isinstance(email, str) and email.strip() else None,
    )


async def _load_slack_people(token: str) -> ProviderList:
    users, truncated = await _slack_paged(token, "users.list", {}, "members")
    options = [o for o in (_slack_person(u) for u in users) if o is not None]
    options.sort(key=lambda o: o.name.lower())
    return ProviderList(configured=True, options=options[:MAX_ITEMS], truncated=truncated)


async def _load_slack_channels(token: str) -> ProviderList:
    params = {"types": "public_channel,private_channel", "exclude_archived": "true"}
    try:
        channels, truncated = await _slack_paged(token, "conversations.list", params, "channels")
    except _SlackError as exc:
        # Without groups:read Slack refuses the whole call: list the public
        # channels rather than nothing.
        if str(exc) != "missing_scope":
            raise
        params["types"] = "public_channel"
        channels, truncated = await _slack_paged(token, "conversations.list", params, "channels")
    options: list[DirectoryOption] = []
    for ch in channels:
        cid, name = ch.get("id"), ch.get("name")
        if not isinstance(cid, str) or not isinstance(name, str):
            continue
        options.append(
            DirectoryOption(id=cid, name=f"#{name}", detail="Private" if ch.get("is_private") else "")
        )
    options.sort(key=lambda o: o.name.lower())
    return ProviderList(configured=True, options=options[:MAX_ITEMS], truncated=truncated)


async def slack_user_by_email(email: str) -> SlackMatch:
    """The Slack person whose profile email is ``email``, or no match."""
    token = get_settings().slack_bot_token
    if not token:
        return SlackMatch(configured=False)
    wanted = email.strip().lower()
    if not wanted or "@" not in wanted:
        return SlackMatch(configured=True)
    # The cached list usually has them already.
    hit = _cache.get(("slack", "people"))
    if hit is not None and time.monotonic() - hit[0] < CACHE_TTL_S:
        for opt in hit[1].options:
            if opt.email == wanted:
                return SlackMatch(configured=True, match=opt)
    try:
        async with client_factory() as client:
            data = await _slack_call(client, token, "users.lookupByEmail", {"email": wanted})
    except _SlackError as exc:
        if str(exc) != "users_not_found":
            logger.warning("chat directory: Slack lookup by email failed: %s", exc)
        return SlackMatch(configured=True)
    except httpx.HTTPError as exc:
        logger.warning("chat directory: Slack lookup by email failed: %s", type(exc).__name__)
        return SlackMatch(configured=True)
    user = data.get("user")
    match = _slack_person(user) if isinstance(user, dict) else None
    return SlackMatch(configured=True, match=match)


# --------------------------------------------------------------------------- #
# Discord
# --------------------------------------------------------------------------- #

class _DiscordRefused(Exception):
    """Discord answered 401/403 (for members: the intent is off)."""


async def _discord_get(client: httpx.AsyncClient, token: str, path: str, **params: Any) -> Any:
    resp = await client.get(
        DISCORD_API + path, params=params or None, headers={"Authorization": f"Bot {token}"}
    )
    if resp.status_code in (401, 403):
        raise _DiscordRefused(str(resp.status_code))
    resp.raise_for_status()
    return resp.json()


async def _discord_guilds(client: httpx.AsyncClient, token: str) -> list[tuple[str, str]]:
    """(id, name) of the servers to list: ``DISCORD_GUILD_IDS`` when set
    (and the bot is in them), else every server the bot is in."""
    data = await _discord_get(client, token, "/users/@me/guilds", limit=200)
    guilds = [
        (str(g["id"]), str(g.get("name") or ""))
        for g in data or []
        # Ids go into request paths: only Discord's numeric snowflakes.
        if isinstance(g, dict) and str(g.get("id") or "").isdigit()
    ]
    only = {str(g) for g in get_settings().discord_guild_ids}
    return [g for g in guilds if g[0] in only] if only else guilds


async def _load_discord_channels(token: str) -> ProviderList:
    options: list[DirectoryOption] = []
    async with client_factory() as client:
        guilds = await _discord_guilds(client, token)
        for gid, gname in guilds:
            channels = await _discord_get(client, token, f"/guilds/{gid}/channels")
            rows = sorted(
                (c for c in channels or [] if isinstance(c, dict) and c.get("type") in _DISCORD_TEXT_TYPES),
                key=lambda c: (c.get("position") or 0, str(c.get("name") or "")),
            )
            options.extend(
                DirectoryOption(id=str(c["id"]), name=f"#{c.get('name') or ''}", detail=gname)
                for c in rows
                if c.get("id") is not None
            )
    truncated = len(options) > MAX_ITEMS
    return ProviderList(configured=True, options=options[:MAX_ITEMS], truncated=truncated)


async def _load_discord_people(token: str) -> ProviderList:
    seen: dict[str, DirectoryOption] = {}
    truncated = False
    async with client_factory() as client:
        guilds = await _discord_guilds(client, token)
        for gid, _gname in guilds:
            after = "0"
            for _ in range(_MAX_PAGES):
                try:
                    page = await _discord_get(
                        client, token, f"/guilds/{gid}/members", limit=1000, after=after
                    )
                except _DiscordRefused:
                    return ProviderList(configured=True, members_available=False)
                members = [m for m in page or [] if isinstance(m, dict)]
                for m in members:
                    user = m.get("user") or {}
                    uid = user.get("id")
                    if uid is None or user.get("bot") or str(uid) in seen:
                        continue
                    username = str(user.get("username") or "")
                    name = str(m.get("nick") or user.get("global_name") or username or uid)
                    seen[str(uid)] = DirectoryOption(
                        id=str(uid), name=name, detail=f"@{username}" if username else ""
                    )
                if len(members) < 1000:
                    break
                after = str((members[-1].get("user") or {}).get("id") or "")
                if not after:
                    break
            else:
                truncated = True
            if len(seen) >= MAX_ITEMS:
                truncated = True
                break
    options = sorted(seen.values(), key=lambda o: o.name.lower())
    return ProviderList(
        configured=True, options=options[:MAX_ITEMS], truncated=truncated, members_available=True
    )


# --------------------------------------------------------------------------- #
# Telegram
# --------------------------------------------------------------------------- #

def _telegram_list(kind: Kind) -> ProviderList:
    from openexecutive.integrations.telegram_chats import list_chats

    chats = list_chats("people" if kind == "people" else "groups")
    options = [
        DirectoryOption(
            id=c.chat_id,
            name=c.title or (f"@{c.username}" if c.username else "Telegram chat"),
            detail=_telegram_detail(
                c,
                verb="first wrote" if kind == "people" else "seen since",
                linked_to=_telegram_linked_name(c.chat_id) if kind == "people" else "",
            ),
        )
        for c in chats
    ]
    return ProviderList(configured=True, options=options)


def _telegram_linked_name(chat_id: str) -> str:
    """Who on the roster already has this Telegram chat, if anyone."""
    from openexecutive.people import store as people_store

    try:
        person = people_store.find_person_by_telegram_chat_id(chat_id, include_contacts=True)
    except Exception:
        return ""
    return person.full_name if person is not None else ""


def _telegram_detail(chat: Any, *, verb: str, linked_to: str) -> str:
    """What tells two chats with the same name apart: anyone can pick their
    own Telegram name, so show the @username, when they first wrote, and who
    already has this chat."""
    parts: list[str] = []
    if chat.username and chat.title:
        parts.append(f"@{chat.username}")
    try:
        first = datetime.fromisoformat(chat.first_seen_at)
        parts.append(f"{verb} {first.strftime('%b')} {first.day}, {first.year}")
    except (TypeError, ValueError):
        pass
    if linked_to:
        parts.append(f"already linked to {linked_to}")
    return " · ".join(parts)


# --------------------------------------------------------------------------- #
# Public
# --------------------------------------------------------------------------- #

_LOADERS: dict[tuple[str, str], Callable[[str], Awaitable[ProviderList]]] = {
    ("slack", "people"): _load_slack_people,
    ("slack", "channels"): _load_slack_channels,
    ("discord", "people"): _load_discord_people,
    ("discord", "channels"): _load_discord_channels,
}


async def _provider_list(provider: Provider, kind: Kind) -> ProviderList:
    settings = get_settings()
    token = {
        "slack": settings.slack_bot_token,
        "discord": settings.discord_bot_token,
        "telegram": settings.telegram_bot_token,
    }[provider]
    if not token:
        return ProviderList(configured=False)
    if provider == "telegram":
        # A local read, fresh each time: a chat that just wrote shows at once.
        try:
            return _telegram_list(kind)
        except Exception:
            logger.exception("chat directory: reading Telegram chats failed")
            return ProviderList(configured=True, ok=False)
    loader = _LOADERS[(provider, kind)]

    async def load() -> ProviderList:
        try:
            return await loader(token)
        except Exception as exc:
            # The exception text can carry a request URL, never a token
            # (tokens go only in headers), but keep the log to its kind.
            logger.warning(
                "chat directory: listing %s %s failed: %s %s",
                provider, kind, type(exc).__name__, exc if isinstance(exc, _SlackError) else "",
            )
            return ProviderList(configured=True, ok=False)

    return await _cached((provider, kind), load)


async def list_directory(kind: Kind) -> DirectoryListing:
    """Every provider's people or channels, fetched side by side."""
    slack, discord, telegram = await asyncio.gather(
        _provider_list("slack", kind),
        _provider_list("discord", kind),
        _provider_list("telegram", kind),
    )
    return DirectoryListing(slack=slack, discord=discord, telegram=telegram)