| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870 |
- """Microsoft Teams adapter: microsoft-teams-apps SDK for auth/activity processing, an aiohttp
- webhook server for inbound, ``App.send()`` for proactive sends.
- Requires the ``teams`` extra (auto-installed by the gateway on first start, or
- ``<hermes-venv>/bin/pip install microsoft-teams-apps aiohttp``) and credentials via env
- (TEAMS_CLIENT_ID / TEAMS_CLIENT_SECRET / TEAMS_TENANT_ID, optional TEAMS_PORT) or
- ``platforms.teams.extra`` in config.yaml (``client_id`` / ``client_secret`` / ``tenant_id`` / ``port``).
- """
- from __future__ import annotations
- import asyncio
- # microsoft-teams-apps calls ``load_dotenv(find_dotenv(usecwd=True))`` at ``microsoft_teams.apps.app``
- # import time. Importing it during plugin discovery / ``TeamsSummaryWriter`` imports would pollute process
- # ``os.environ`` from a cwd-discovered ``.env`` (#62935). Detect presence via find_spec only; bind symbols
- # in ``check_teams_requirements()`` behind a dotenv no-op.
- import importlib.util
- import json
- import logging
- import re
- import sys
- import uuid
- from collections import deque
- from contextlib import contextmanager, suppress
- from pathlib import Path
- from typing import Any, Dict, Iterator, Optional
- from urllib.parse import urlparse
- try:
- from aiohttp import web
- AIOHTTP_AVAILABLE = True
- except ImportError:
- AIOHTTP_AVAILABLE = False
- web = None # type: ignore[assignment]
- def _probe_teams_sdk_available() -> bool:
- """True when ``microsoft_teams.apps`` is on sys.path, without importing it: the SDK loads a cwd
- ``.env`` at import, so ``check_teams_requirements()`` binds symbols behind a dotenv no-op.
- Sibling packages share the namespace, so probe the parent first — ``find_spec`` of the child
- raises on 3.11+ if the parent is absent."""
- try:
- find_spec = importlib.util.find_spec
- return find_spec("microsoft_teams") is not None and find_spec("microsoft_teams.apps") is not None
- except (ValueError, ModuleNotFoundError, ImportError):
- return "microsoft_teams.apps" in sys.modules # test stubs may lack ``__spec__``
- TEAMS_SDK_AVAILABLE = _probe_teams_sdk_available()
- # SDK symbols stay None until check_teams_requirements() binds them (via _SDK_IMPORTS below).
- ClientOptions = App = ActivityContext = MessageActivity = ConversationReference = None # type: ignore[assignment,misc]
- TypingActivityInput = AdaptiveCardInvokeActivity = AdaptiveCardActionCardResponse = None # type: ignore[assignment,misc]
- AdaptiveCardActionMessageResponse = AdaptiveCardInvokeResponse = InvokeResponse = None # type: ignore[assignment,misc]
- HttpRequest = HttpResponse = HttpRouteHandler = AdaptiveCard = ExecuteAction = TextBlock = None # type: ignore[assignment,misc]
- HttpMethod = str # type: ignore[assignment,misc]
- from gateway.config import Platform, PlatformConfig
- from gateway.platforms.helpers import MessageDeduplicator
- from gateway.platforms.base import (
- gateway_trust_env, BasePlatformAdapter, ExecApprovalPrompt, SendResult, cache_image_from_url, cache_media_bytes_async,
- )
- from gateway.platforms.base_exec_approval import approval_timeout_seconds, format_approval_deadline_line
- from agent.i18n import t
- from gateway.platforms.event import MessageEvent, MessageType
- from gateway.platforms._shared import (
- coerce_port, extra_or_secret as _extra_or_secret, get_scoped_secret as _get_scoped_secret,
- seed_extra_from_env as _seed_extra_from_env, send_error
- )
- logger = logging.getLogger(__name__)
- _DEFAULT_PORT = 3978
- _MAX_BODY_BYTES = 1_048_576 # Bot Framework activities are JSON well under 1 MiB
- # ``None`` host → aiohttp binds IPv4 + IPv6 ("0.0.0.0" was unreachable on IPv6-only
- # networks such as Fly.io 6PN). Pin via TEAMS_HOST or extra.host.
- _DEFAULT_HOST = None
- _WEBHOOK_PATH = "/api/messages"
- # Regional/government tenants override via ``TEAMS_SERVICE_URL`` / ``extra['service_url']``.
- _DEFAULT_TEAMS_SERVICE_URL = "https://smba.trafficmanager.net/teams/"
- # Hosts that may receive a freshly minted bearer token (blocks SSRF / token exfiltration via a
- # tampered env var). Exact match only: any Azure customer can register ``<name>.trafficmanager.net``.
- _ALLOWED_TEAMS_SERVICE_HOSTS = frozenset({"smba.trafficmanager.net", "smba.infra.gov.teams.microsoft.us"})
- # Conservative conversation-ID charset (``thread.skype`` / ``thread.tacv2`` suffixes included) so a
- # hostile value cannot path-traverse out of ``/v3/conversations/<id>/activities``.
- _TEAMS_CONV_ID_RE = re.compile(r"^[A-Za-z0-9:@\-_.]+$")
- _BF_TOKEN_SCOPE = "https://api.botframework.com/.default"
- def _bf_token_request(tenant_id: str, client_id: str, client_secret: str) -> tuple[str, dict]:
- """(token URL, client-credentials form) for a Bot Framework bearer token."""
- return (
- f"https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token",
- {"grant_type": "client_credentials", "client_id": client_id, "client_secret": client_secret, "scope": _BF_TOKEN_SCOPE},
- )
- def _is_allowed_https_host(url: str, *, check_port: bool = False) -> bool:
- """https + host in ``_ALLOWED_TEAMS_SERVICE_HOSTS`` (+ default port when asked)."""
- try:
- parsed = urlparse(url)
- if parsed.scheme != "https" or (check_port and parsed.port not in (None, 443)):
- return False
- return parsed.hostname in _ALLOWED_TEAMS_SERVICE_HOSTS
- except Exception:
- return False
- def _is_botframework_attachment_url(url: str) -> bool:
- """True if ``url`` is a Bot Framework connector attachment host (may carry the bot token)."""
- return _is_allowed_https_host(url, check_port=True)
- def _validate_teams_service_url(raw: str) -> Optional[str]:
- """Normalized (trailing-slash) service URL, or ``None`` if not on the allowlist."""
- if not raw or not _is_allowed_https_host(raw):
- return None
- return raw if raw.endswith("/") else raw + "/"
- class _AiohttpBridgeAdapter:
- """HttpServerAdapter bridging SDK route registrations into our aiohttp app; without it
- ``App()`` unconditionally imports fastapi/uvicorn and allocates a ``FastAPI()``."""
- def __init__(self, aiohttp_app: web.Application):
- self._aiohttp_app = aiohttp_app
- def register_route(self, method: HttpMethod, path: str, handler: HttpRouteHandler) -> None:
- async def _aiohttp_handler(request: web.Request) -> web.Response:
- result: HttpResponse = await handler(HttpRequest(body=await request.json(), headers=dict(request.headers)))
- status = result.get("status", 200)
- resp_body = result.get("body")
- if resp_body is not None:
- return web.Response(status=status, body=json.dumps(resp_body), content_type="application/json")
- return web.Response(status=status)
- self._aiohttp_app.router.add_route(method, path, _aiohttp_handler)
- def serve_static(self, path: str, directory: str) -> None:
- pass
- async def start(self, port: int) -> None:
- raise NotImplementedError("aiohttp server is managed by the adapter")
- async def stop(self) -> None:
- pass
- def check_requirements() -> bool:
- """PASSIVE probe (registry ``check_fn``): SDK + aiohttp importable? Never installs."""
- return TEAMS_SDK_AVAILABLE and AIOHTTP_AVAILABLE
- def _credentials(config) -> tuple[str, str, str]:
- """(client_id, client_secret, tenant_id): ``config.extra`` first, then the profile-scoped env.
- client_id/tenant_id are read through the same scoped reader as the secret: under multiplex,
- ``os.environ`` holds the DEFAULT profile's app identity, and pairing it with a secondary's
- secret requests a Bot Framework token for the wrong app. ``extra`` wins so a per-profile
- config.yaml identity is never overridden by the process env.
- """
- extra = getattr(config, "extra", {}) or {}
- return (
- extra.get("client_id") or _get_scoped_secret("TEAMS_CLIENT_ID", ""),
- extra.get("client_secret") or _get_scoped_secret("TEAMS_CLIENT_SECRET", ""),
- extra.get("tenant_id") or _get_scoped_secret("TEAMS_TENANT_ID", ""))
- def validate_config(config) -> bool:
- return bool(all(_credentials(config)))
- def is_connected(config) -> bool:
- return validate_config(config)
- def _env_enablement() -> dict | None:
- """``env_enablement_fn``: seed ``PlatformConfig.extra`` from the profile's env before adapter construction
- so ``gateway status`` reflects env-only setups without the SDK; ``None`` when not minimally configured.
- Every identity/endpoint is per-profile (the app the secret belongs to, its regional service URL, the
- cron home conversation), so a secondary is never seeded with the default profile's Teams app."""
- seed = _seed_extra_from_env((
- ("TEAMS_CLIENT_ID", "client_id", None), ("TEAMS_CLIENT_SECRET", "client_secret", None),
- ("TEAMS_TENANT_ID", "tenant_id", None), ("TEAMS_PORT", "port", int), ("TEAMS_SERVICE_URL", "service_url", None),
- ), home_env="TEAMS_HOME_CHANNEL")
- if not all(seed.get(k) for k in ("client_id", "client_secret", "tenant_id")):
- return None
- return seed
- async def _standalone_send(
- pconfig, chat_id: str, message: str, *,
- thread_id: Optional[str] = None, media_files: Optional[list] = None, force_document: bool = False,
- ) -> dict[str, Any]:
- """Acquire a Bot Framework bearer token and POST a single message activity; used by
- ``send_message_tool._send_via_adapter`` when the gateway runner is not in this process
- (``hermes cron``). ``TEAMS_SERVICE_URL`` is allowlisted and ``chat_id`` charset-checked
- (SSRF/path traversal). ``media_files`` / ``force_document`` are signature parity only — text-only."""
- extra = getattr(pconfig, "extra", {}) or {}
- client_id, client_secret, tenant_id = _credentials(pconfig)
- if not (client_id and client_secret and tenant_id):
- return send_error("Teams standalone send: TEAMS_CLIENT_ID, TEAMS_CLIENT_SECRET, and TEAMS_TENANT_ID are all required")
- raw_service_url = extra.get("service_url") or _get_scoped_secret("TEAMS_SERVICE_URL", "") or _DEFAULT_TEAMS_SERVICE_URL
- service_url = _validate_teams_service_url(raw_service_url)
- for failed, error in (
- (service_url is None, f"TEAMS_SERVICE_URL host is not on the Bot Framework allowlist; "
- f"expected one of {sorted(_ALLOWED_TEAMS_SERVICE_HOSTS)}"),
- (not chat_id, "chat_id (conversation ID) is required"),
- (not _TEAMS_CONV_ID_RE.match(chat_id or ""), "chat_id contains characters outside the Bot Framework conversation ID set"),
- (not _TEAMS_CONV_ID_RE.match(tenant_id), "TEAMS_TENANT_ID contains characters outside the expected set"),
- (not AIOHTTP_AVAILABLE, "aiohttp not installed")):
- if failed:
- return send_error(f"Teams standalone send: {error}")
- token_url, token_form = _bf_token_request(tenant_id, client_id, client_secret)
- activities_url = f"{service_url}v3/conversations/{chat_id}/activities"
- try:
- import aiohttp as _aiohttp
- # Per-request timeouts so a slow STS endpoint cannot starve the activity POST.
- per_request_timeout = _aiohttp.ClientTimeout(total=15.0)
- async with _aiohttp.ClientSession(trust_env=gateway_trust_env()) as session:
- async with session.post(
- token_url, data=token_form, headers={"Content-Type": "application/x-www-form-urlencoded"},
- timeout=per_request_timeout,
- ) as token_resp:
- if token_resp.status >= 400:
- body = await token_resp.text()
- return send_error(f"Teams standalone send: token request failed ({token_resp.status}): {body[:300]}")
- token_payload = await token_resp.json()
- access_token = token_payload.get("access_token")
- if not access_token:
- return send_error("Teams standalone send: token response missing access_token")
- async with session.post(
- activities_url, json={"type": "message", "text": message, "textFormat": "markdown"},
- headers={"Authorization": f"Bearer {access_token}", "Content-Type": "application/json"},
- timeout=per_request_timeout,
- ) as send_resp:
- if send_resp.status >= 400:
- body = await send_resp.text()
- return send_error(f"Teams standalone send: activity post failed ({send_resp.status}): {body[:300]}")
- send_payload = await send_resp.json()
- return {"success": True, "message_id": send_payload.get("id")}
- except asyncio.CancelledError:
- raise
- except Exception as e:
- logger.debug("Teams standalone send raised", exc_info=True)
- return send_error(f"Teams standalone send failed: {e}")
- # SDK module → names rebound into this module's globals by check_teams_requirements().
- _SDK_IMPORTS = {
- "microsoft_teams.apps": ("App", "ActivityContext"),
- "microsoft_teams.common.http.client": ("ClientOptions",),
- "microsoft_teams.api": ("MessageActivity", "ConversationReference"),
- "microsoft_teams.api.activities.typing": ("TypingActivityInput",),
- "microsoft_teams.api.activities.invoke.adaptive_card": ("AdaptiveCardInvokeActivity",),
- "microsoft_teams.api.models.adaptive_card": ("AdaptiveCardActionCardResponse", "AdaptiveCardActionMessageResponse"),
- "microsoft_teams.api.models.invoke_response": ("InvokeResponse", "AdaptiveCardInvokeResponse"),
- "microsoft_teams.apps.http.adapter": ("HttpMethod", "HttpRequest", "HttpResponse", "HttpRouteHandler"),
- "microsoft_teams.cards": ("AdaptiveCard", "ExecuteAction", "TextBlock")}
- # NOTE: ``check_requirements`` is the
- # PASSIVE probe (registry ``check_fn``, status / unit tests) — it must never trigger a pip install.
- # ``check_teams_requirements`` is the ACTIVE lazy-installer, registered as ``ensure_deps_fn``: the
- # registry's ``create_adapter()`` runs it when the passive probe fails, right before the gateway connects
- # Teams (#79812). ``connect()`` re-checks defensively.
- @contextmanager
- def _suppress_third_party_dotenv() -> Iterator[None]:
- """No-op ``dotenv.load_dotenv`` while importing the Teams SDK: ``microsoft_teams.apps.app`` loads a
- cwd-discovered ``.env`` at import, mutating process-global ``os.environ``. Hermes owns dotenv loading.
- See #62935.
- """
- try:
- import dotenv as _dotenv
- except ImportError:
- _dotenv = None
- original = getattr(_dotenv, "load_dotenv", None)
- if original is None:
- yield
- return
- _dotenv.load_dotenv = lambda *args, **kwargs: False # type: ignore[assignment]
- try:
- yield
- finally:
- _dotenv.load_dotenv = original # type: ignore[assignment]
- def check_teams_requirements() -> bool:
- """Ensure the Teams SDK is importable, lazy-installing it on first use.
- Lazy-installs ``microsoft-teams-apps`` via
- ``pm.ensure_import("teams")`` if not present, then rebinds
- all module-level SDK globals on success. Returns True once the SDK (and
- aiohttp) are importable, False if they couldn't be installed/imported.
- ``App is not None`` means symbols are already bound — ``TEAMS_SDK_AVAILABLE``
- alone can be True from ``find_spec`` without an import having run yet.
- """
- if App is not None and AIOHTTP_AVAILABLE:
- return True
- def _import() -> dict:
- from aiohttp import web as _web
- bindings: dict = {"web": _web, "AIOHTTP_AVAILABLE": True}
- with _suppress_third_party_dotenv():
- for module_name, names in _SDK_IMPORTS.items():
- module = importlib.import_module(module_name)
- for name in names:
- try:
- bindings[name] = getattr(module, name)
- except AttributeError as exc: # same failure class as ``from X import Y``
- raise ImportError(f"cannot import name {name!r} from {module_name!r}") from exc
- bindings["TEAMS_SDK_AVAILABLE"] = True
- return bindings
- from pm.extras import ensure_and_bind
- return ensure_and_bind("teams", _import, globals())
- _CHAT_TYPES = {"personal": "dm", "groupChat": "group", "channel": "channel"}
- # DOCUMENT wins over PHOTO/VIDEO/AUDIO for mixed attachments: document-context
- # injection gates strictly on MessageType.DOCUMENT (same precedence as Email/Signal).
- _MEDIA_KIND_PRECEDENCE = (
- ("document", MessageType.DOCUMENT), ("image", MessageType.PHOTO),
- ("video", MessageType.VIDEO), ("audio", MessageType.AUDIO))
- _APPROVAL_CHOICES = {"approve_once": "once", "approve_session": "session", "approve_always": "always", "deny": "deny"}
- # choice → catalog key of the card footer; resolved through ``t()`` at click time, never at import.
- _APPROVAL_LABEL_KEYS = {
- "once": "platform.teams.approval.resolved_once", "session": "platform.teams.approval.resolved_session",
- "always": "platform.teams.approval.resolved_always", "deny": "platform.teams.approval.resolved_deny",
- }
- def _approval_body(cmd: str, desc: str, *, always: bool = False) -> list:
- """Adaptive Card body blocks for an approval prompt; unless ``always``, empty ``cmd``/``desc`` omit their blocks."""
- body = []
- if cmd or always:
- body.append(TextBlock(text=f"⚠️ {t('gateway.exec_approval.header')}", wrap=True, weight="Bolder"))
- body.append(TextBlock(text=f"```\n{cmd}\n```", wrap=True))
- if desc or always:
- body.append(TextBlock(text=f"{t('gateway.exec_approval.reason_label')}: {desc}", wrap=True, isSubtle=True))
- return body
- class TeamsAdapter(BasePlatformAdapter):
- """Microsoft Teams adapter using the microsoft-teams-apps SDK."""
- # Answers /p/<profile>/... on the default listener for a served secondary (shared_ingress).
- serves_profile_prefix: bool = True
- MAX_MESSAGE_LENGTH = 28000 # Teams text message limit (~28 KB)
- splits_long_messages = True # send() chunks via truncate_message()
- def __init__(self, config: PlatformConfig):
- super().__init__(config, Platform("teams"))
- # Kept on the instance: ``platforms.teams.extra.*`` keys are read after construction too.
- self._extra: dict[str, Any] = config.extra or {}
- self._client_id, self._client_secret, self._tenant_id = _credentials(config)
- # (token, expiry monotonic ts) for connector attachment auth; refreshed under
- # _bf_token_lock so concurrent attachments can't stampede the STS.
- self._bf_token_cache: Optional[tuple] = None
- self._bf_token_lock: Optional[asyncio.Lock] = None
- self._port = coerce_port(self._extra.get("port") or _get_scoped_secret("TEAMS_PORT", str(_DEFAULT_PORT)), _DEFAULT_PORT)
- _raw_host = self._extra.get("host") or _get_scoped_secret("TEAMS_HOST", "") or _DEFAULT_HOST # falsy → dual-stack None
- self._host: Optional[str] = str(_raw_host) if _raw_host else None
- self._app: Optional[App] = None
- self._runner: Optional[web.AppRunner] = None
- self._dedup = MessageDeduplicator(max_size=1000)
- # chat_id → ConversationReference so proactive cards use the right conversation type.
- self._conv_refs: dict[str, Any] = {}
- self._require_mention: bool = self._parse_require_mention(config)
- # Outbound activity ids (bounded) so require_mention can exempt replies to our own messages.
- self._sent_ids: deque = deque(maxlen=500)
- # prompt id → (command preview, reason) for the resolved card; button data carries only the id,
- # because a copy per button can push a long non-ASCII command past Teams' ~28 KB card cap.
- self._approval_previews: dict[str, tuple[str, str]] = {}
- @staticmethod
- def _parse_require_mention(config) -> bool:
- """TEAMS_REQUIRE_MENTION (scoped) → ``require_mention`` in config.extra → false (opt-in, same
- default as TELEGRAM_REQUIRE_MENTION). Without RSC Teams only delivers mention activities to a
- group bot anyway, so the gate changes nothing until the app gains ChannelMessage.Read.Group /
- ChatMessage.Read.Chat and starts receiving every conversation message."""
- configured = _extra_or_secret(config.extra, "require_mention", "TEAMS_REQUIRE_MENTION", False)
- if isinstance(configured, bool):
- return configured
- return str(configured).strip().lower() not in {"false", "0", "no", "off"}
- async def connect(self, *, is_reconnect: bool = False) -> bool:
- # Reconnect paths reach here without create_adapter()'s installer — re-run to bind SDK globals.
- check_teams_requirements()
- pip = f"{sys.executable} -m pip install"
- for failed, code, message in (
- (App is None or ClientOptions is None, "MISSING_SDK",
- f"microsoft-teams-apps could not be installed. Run: {pip} microsoft-teams-apps"),
- (not AIOHTTP_AVAILABLE, "MISSING_SDK", f"aiohttp not installed. Run: {pip} aiohttp"),
- (not self._client_id or not self._client_secret or not self._tenant_id, "MISSING_CREDENTIALS",
- "TEAMS_CLIENT_ID, TEAMS_CLIENT_SECRET, and TEAMS_TENANT_ID are all required")):
- if failed:
- self._set_fatal_error(code, message, retryable=False)
- return False
- try:
- # aiohttp app first — the bridge adapter wires SDK routes into it.
- # Set up aiohttp app first — the bridge adapter wires SDK routes into it. client_max_size: Bot
- # Framework activities are JSON (caps out well under 1 MiB); an explicit cap keeps
- # oversized/chunked bodies from being buffered unbounded on a 0.0.0.0 bind (same pattern as
- # webhook.py / raft, #58536/#58902).
- aiohttp_app = web.Application(client_max_size=_MAX_BODY_BYTES)
- aiohttp_app.router.add_get("/health", lambda _: web.Response(text="ok"))
- self._app = App(
- client_id=self._client_id, client_secret=self._client_secret, tenant_id=self._tenant_id,
- http_server_adapter=_AiohttpBridgeAdapter(aiohttp_app),
- client=ClientOptions(headers={"User-Agent": "Hermes"}))
- # Handlers (ours, then plugin on_* decorators) must be wired before initialize(),
- # which registers POST /api/messages on aiohttp_app via the bridge's register_route().
- @self._app.on_message
- async def _handle_message(ctx: ActivityContext[MessageActivity]):
- await self._on_message(ctx)
- @self._app.on_card_action
- async def _handle_card_action(
- ctx: ActivityContext[AdaptiveCardInvokeActivity],
- ) -> InvokeResponse[AdaptiveCardActionMessageResponse]:
- return await self._on_card_action(ctx)
- self._wire_plugin_handlers(self._app)
- await self._app.initialize()
- # Shared-listener mode (multiplex secondary): no bind; served at /p/<profile>/api/messages.
- from gateway.platforms.shared_ingress import bind_listener
- self._runner = await bind_listener(self, aiohttp_app, self._host, self._port, _WEBHOOK_PATH)
- self._running = True
- self._mark_connected()
- if self._runner is not None:
- logger.info(
- "[teams] Webhook server listening on %s:%d%s",
- self._host or "* (all interfaces, IPv4+IPv6)", self._port, _WEBHOOK_PATH)
- return True
- except Exception as e:
- self._set_fatal_error("CONNECT_FAILED", f"Teams connection failed: {e}", retryable=True)
- logger.error("[teams] Failed to connect: %s", e, exc_info=True)
- return False
- async def disconnect(self) -> None:
- self._running = False
- if self._runner:
- await self._runner.cleanup()
- self._runner = self._app = None
- self._mark_disconnected()
- logger.info("[teams] Disconnected")
- async def _get_botframework_token(self) -> str:
- """Bot Framework bearer token (client credentials), cached until ~5 min before expiry; connector
- attachments are NOT pre-authenticated, unlike SharePoint downloadUrls. The lock is created lazily
- because ``asyncio.Lock()`` in __init__ may bind the wrong loop."""
- import time
- import httpx
- if self._bf_token_lock is None:
- self._bf_token_lock = asyncio.Lock()
- async with self._bf_token_lock:
- cached = self._bf_token_cache
- if cached and cached[1] > time.monotonic() + 300:
- return cached[0]
- if not (self._client_id and self._client_secret and self._tenant_id):
- raise ValueError("Missing TEAMS_CLIENT_ID/SECRET/TENANT_ID for attachment auth")
- token_url, token_form = _bf_token_request(self._tenant_id, self._client_id, self._client_secret)
- async with httpx.AsyncClient(timeout=15.0) as client:
- resp = await client.post(token_url, data=token_form)
- resp.raise_for_status()
- payload = resp.json()
- expires_in = float(payload.get("expires_in", 3600) or 3600)
- self._bf_token_cache = (payload["access_token"], time.monotonic() + expires_in)
- return self._bf_token_cache[0]
- async def _fetch_attachment_bytes(self, url: str, timeout: float = 30.0) -> bytes:
- """Download attachment bytes with SSRF protection. Connector URLs get the bot's bearer token;
- redirects and body size go through the shared guards (as the cache_*_from_url helpers)."""
- from tools.url_safety import create_ssrf_safe_async_client, is_safe_url
- from gateway.platforms.base import ssrf_redirect_guard, _read_httpx_body_with_limit
- if not is_safe_url(url):
- raise ValueError("Blocked unsafe attachment URL (SSRF protection)")
- headers = {"User-Agent": "Mozilla/5.0 (compatible; HermesAgent/1.0)"}
- if _is_botframework_attachment_url(url):
- try:
- headers["Authorization"] = f"Bearer {await self._get_botframework_token()}"
- except Exception as e:
- logger.warning("[teams] Could not acquire Bot Framework token for attachment: %s", e)
- async with create_ssrf_safe_async_client(
- timeout=timeout, follow_redirects=True, event_hooks={"response": [ssrf_redirect_guard]}) as client:
- async with client.stream("GET", url, headers=headers) as response:
- response.raise_for_status()
- # Never buffer .content — a lying Content-Length must not OOM the gateway.
- return await _read_httpx_body_with_limit(response, media_type="attachment")
- async def _on_message(self, ctx: ActivityContext[MessageActivity]) -> None:
- activity = ctx.activity
- # Teams writes the bot's conversation identity as ``28:<app id>`` (activity.recipient) while
- # App.id is the bare app id — accept both when deciding "is this us".
- recipient_id = getattr(getattr(activity, "recipient", None), "id", None)
- bot_ids = {i for i in (self._app.id if self._app else None, recipient_id) if isinstance(i, str) and i}
- bot_ids |= {f"28:{i}" for i in tuple(bot_ids) if not i.startswith("28:")}
- if getattr(activity.from_, "id", None) in bot_ids:
- return
- msg_id = getattr(activity, "id", None)
- if msg_id and self._dedup.is_duplicate(msg_id):
- return
- conv = activity.conversation
- conv_id = getattr(conv, "id", None)
- if conv_id: # cache the conversation reference for proactive sends (approval cards, etc.)
- self._conv_refs[conv_id] = ctx.conversation_ref
- text = activity.text if hasattr(activity, "text") and activity.text else ""
- if self._require_mention and getattr(conv, "conversation_type", None) != "personal":
- # RSC-delivered history: every channel/groupChat message arrives. Keep the ones that
- # @mention the bot or reply to one of its own messages; drop the rest BEFORE the
- # attachment loop so a gated post never downloads anything onto the host.
- if not self._activity_mentions_bot(activity, bot_ids, text) and getattr(activity, "reply_to_id", None) not in self._sent_ids:
- logger.debug("[teams] Dropping non-personal message without a bot mention (chat=%s, msg=%s)", conv_id, msg_id)
- return
- if "<at>" in text: # strip the <at>BotName</at> tags Teams prepends for @mentions
- text = re.sub(r"<at>[^<]*</at>\s*", "", text).strip()
- from_account = activity.from_
- user_id = getattr(from_account, "aad_object_id", None) or getattr(from_account, "id", "")
- source = self.build_source(
- chat_id=conv.id,
- chat_name=getattr(conv, "name", None) or "",
- chat_type=_CHAT_TYPES.get(getattr(conv, "conversation_type", None) or "", "dm"),
- user_id=str(user_id),
- user_name=getattr(from_account, "name", None) or "",
- guild_id=getattr(conv, "tenant_id", None) or self._tenant_id,
- message_id=msg_id)
- media: list = [m for m in [await self._cache_attachment(a) for a in getattr(activity, "attachments", None) or []] if m]
- media_kinds = [kind for _, _, kind in media] # media items are (path, media_type, kind)
- msg_type = next((t for kind, t in _MEDIA_KIND_PRECEDENCE if kind in media_kinds), MessageType.TEXT)
- await self.handle_message(MessageEvent(
- text=text, source=source, message_type=msg_type, message_id=msg_id,
- media_urls=[path for path, _, _ in media], media_types=[mt for _, mt, _ in media]))
- @staticmethod
- def _activity_mentions_bot(activity: Any, bot_ids: set, text: str) -> bool:
- """True when a ``mention`` entity points at the bot (``mentioned.id`` is ``28:<app id>`` on the
- wire; ``bot_ids`` carries both spellings). A payload with no mention entities at all falls back
- to the rendered ``<at>`` tag; one that mentions only other people does not."""
- mentions = [e for e in getattr(activity, "entities", None) or [] if getattr(e, "type", None) == "mention"]
- if not mentions:
- return "<at>" in text
- return any(str(getattr(getattr(e, "mentioned", None), "id", "")) in bot_ids for e in mentions)
- async def _cache_attachment(self, att: Any) -> Optional[tuple]:
- """Download + cache one inbound attachment → ``(path, media_type, kind)`` or ``None``."""
- content_url = getattr(att, "content_url", None)
- content_type = (getattr(att, "content_type", None) or "").lower()
- att_name = getattr(att, "name", None) or ""
- # Skip non-file payloads: Teams mirrors the message body as a text/html attachment,
- # and cards arrive as application/vnd.microsoft.card.*
- if (content_type in ("text/html", "text/plain") and not content_url) or content_type.startswith("application/vnd.microsoft.card"):
- return None
- if content_type == "application/vnd.microsoft.teams.file.download.info":
- # Consent-free download: content carries a pre-authed SharePoint downloadUrl + file type.
- content = getattr(att, "content", None)
- if not isinstance(content, dict):
- content = getattr(content, "__dict__", None) or {}
- download_url = content.get("downloadUrl") or content.get("download_url")
- file_type = (content.get("fileType") or content.get("file_type") or "").lstrip(".")
- if not download_url:
- return None
- filename = att_name or (f"document.{file_type}" if file_type else "document")
- try:
- data = await self._fetch_attachment_bytes(download_url)
- cached = await cache_media_bytes_async(data, filename=filename, mime_type="")
- if not cached:
- logger.warning("[teams] Unsupported document type for attachment '%s', skipping", filename)
- return None
- return cached.path, cached.media_type, cached.kind
- except Exception as e:
- logger.warning("[teams] Failed to cache file attachment '%s': %s", filename, e)
- return None
- if content_url and content_type.startswith("image/"):
- try:
- if _is_botframework_attachment_url(content_url):
- # Connector URL needs the bot's bearer token; the generic cache helper sends none.
- data = await self._fetch_attachment_bytes(content_url)
- ext = content_type.split("/")[-1].split(";")[0] or "png"
- cached = await cache_media_bytes_async(data, filename=att_name or f"image.{ext}", mime_type=content_type)
- if not cached:
- logger.warning(
- "[teams] Bot Framework attachment '%s' returned data that failed image validation, skipping",
- att_name or content_url)
- return None
- return cached.path, cached.media_type, "image"
- path = await cache_image_from_url(content_url)
- return (path, content_type, "image") if path else None
- except Exception as e:
- logger.warning("[teams] Failed to cache image attachment: %s", e)
- return None
- if content_url: # direct-URL non-image attachment (video/audio/document)
- try:
- data = await self._fetch_attachment_bytes(content_url)
- cached = await cache_media_bytes_async(data, filename=att_name, mime_type=content_type)
- return (cached.path, cached.media_type, cached.kind) if cached else None
- except Exception as e:
- logger.warning("[teams] Failed to cache attachment '%s' (%s): %s", att_name or content_url, content_type, e)
- return None
- async def _send_card(self, chat_id: str, card: AdaptiveCard) -> Any:
- """Send an AdaptiveCard, using a stored ConversationReference when available."""
- from microsoft_teams.api import MessageActivityInput
- if not self._app:
- return None
- return await self._send_via_conv_ref(chat_id, MessageActivityInput().add_card(card), card)
- async def _send_via_conv_ref(self, chat_id: str, activity: Any, fallback: Any) -> Any:
- """Send ``activity`` through the cached ConversationReference, else ``App.send(fallback)``."""
- conv_ref = self._conv_refs.get(chat_id)
- if conv_ref:
- result = await self._app.activity_sender.send(activity, conv_ref)
- else:
- result = await self._app.send(chat_id, fallback)
- self._remember_sent(result)
- return result
- def _remember_sent(self, result: Any) -> None:
- """Track an outbound activity id (bounded deque) for the require_mention reply exemption."""
- sent_id = getattr(result, "id", None)
- if isinstance(sent_id, str) and sent_id:
- self._sent_ids.append(sent_id)
- @staticmethod
- def _invoke_message(text: str) -> InvokeResponse[AdaptiveCardActionMessageResponse]:
- return InvokeResponse(status=200, body=AdaptiveCardActionMessageResponse(value=text))
- @staticmethod
- def _invoke_card(body: list) -> InvokeResponse[AdaptiveCardActionMessageResponse]:
- card = AdaptiveCard().with_version("1.4").with_body(body)
- return InvokeResponse(status=200, body=AdaptiveCardActionCardResponse(value=card))
- async def _on_card_action(
- self, ctx: ActivityContext[AdaptiveCardInvokeActivity]
- ) -> InvokeResponse[AdaptiveCardActionMessageResponse]:
- from tools.approval import has_blocking_approval, resolve_gateway_approval_card
- data = ctx.activity.value.action.data or {}
- hermes_action = data.get("hermes_action", "")
- session_key = data.get("session_key", "")
- if not hermes_action or not session_key:
- return self._invoke_message(t("platform.teams.approval.unknown_action"))
- denied = self._card_action_denied(ctx.activity.from_)
- if denied:
- return self._invoke_message(denied)
- choice = _APPROVAL_CHOICES.get(hermes_action)
- if not choice:
- return self._invoke_message(t("platform.teams.approval.unknown_action"))
- # Cards from an older build carry cmd/desc in the button data instead.
- cmd, desc = self._approval_previews.get(data.get("prompt_id", ""), (data.get("cmd", ""), data.get("desc", "")))
- if not has_blocking_approval(session_key) or not resolve_gateway_approval_card(
- session_key, choice, data.get("request_id")):
- body = _approval_body(cmd, desc)
- return self._invoke_card([*body, TextBlock(text=t("platform.shared.approval_expired"), wrap=True)])
- body = _approval_body(cmd, desc)
- body.append(TextBlock(text=t(_APPROVAL_LABEL_KEYS[choice]), wrap=True, weight="Bolder"))
- return self._invoke_card(body)
- @staticmethod
- def _card_action_denied(from_account: Any) -> Optional[str]:
- """Default-deny gate for approval clicks: require TEAMS_ALLOWED_USERS or an explicit
- TEAMS_ALLOW_ALL_USERS=true opt-in, else anyone who can message the bot could approve.
- Returns the user-facing denial text, or ``None`` when allowed."""
- # Scoped reads: under multiplex os.environ is the DEFAULT profile's allow-all/allowlist.
- if _get_scoped_secret("TEAMS_ALLOW_ALL_USERS", "").strip().lower() in {"1", "true", "yes"}:
- return None
- allowed_csv = _get_scoped_secret("TEAMS_ALLOWED_USERS", "").strip()
- if not allowed_csv:
- logger.warning(
- "[teams] card action rejected: TEAMS_ALLOWED_USERS not configured "
- "and TEAMS_ALLOW_ALL_USERS not set — default deny")
- return t("platform.teams.approval.requires_allowlist")
- clicker_id = getattr(from_account, "aad_object_id", None) or getattr(from_account, "id", "")
- allowed_ids = {uid.strip() for uid in allowed_csv.split(",") if uid.strip()}
- if "*" not in allowed_ids and clicker_id not in allowed_ids:
- logger.warning("[teams] Unauthorized card action by %s — ignoring", clicker_id)
- return t("platform.shared.not_authorized")
- return None
- _EA_CMD_BUDGET = 2000
- _EA_PREVIEWS_KEPT = 256
- _EA_CARD_ACTIONS = {"once": "approve_once", "session": "approve_session", "always": "approve_always", "deny": "deny"}
- _EA_CARD_STYLES = {"primary": "positive", "danger": "destructive"}
- async def _send_exec_approval_prompt(self, prompt: ExecApprovalPrompt) -> SendResult:
- """Adaptive Card: the shared text is split into its header / fenced command / reason blocks."""
- if not self._app:
- return SendResult(success=False, error="Teams app not initialized")
- # The resolved card shows the prompt's own command preview, looked up by id on click.
- cmd = self._truncate_preview(prompt.command, self._EA_CMD_BUDGET)
- prompt_id = uuid.uuid4().hex
- self._approval_previews[prompt_id] = (cmd, prompt.description)
- if len(self._approval_previews) > self._EA_PREVIEWS_KEPT:
- self._approval_previews.pop(next(iter(self._approval_previews)))
- btn_data_base = {"session_key": prompt.session_key, "prompt_id": prompt_id}
- if prompt.request_id:
- btn_data_base["request_id"] = prompt.request_id
- actions = []
- for label, choice, style in prompt.actions:
- kw = {"style": self._EA_CARD_STYLES[style]} if style else {}
- actions.append(ExecuteAction(
- title=label, verb="hermes_approve",
- data={**btn_data_base, "hermes_action": self._EA_CARD_ACTIONS[choice]}, **kw))
- body = _approval_body(cmd, prompt.description, always=True)
- body.append(TextBlock(text=format_approval_deadline_line(approval_timeout_seconds()), wrap=True))
- if prompt.smart_denied:
- body.append(TextBlock(text=self._EA_SMART_DENY_LINE.strip(), wrap=True))
- card = AdaptiveCard().with_version("1.4").with_body(body).with_actions(actions)
- try:
- result = await self._send_card(prompt.chat_id, card)
- return SendResult(success=True, message_id=getattr(result, "id", None) if result else None)
- except Exception as e:
- logger.error("[teams] send_exec_approval failed: %s", e, exc_info=True)
- return SendResult(success=False, error=str(e), retryable=True)
- async def send(
- self, chat_id: str, content: str, reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None
- ) -> SendResult:
- if not self._app:
- return SendResult(success=False, error="Teams app not initialized")
- last_message_id = None
- for chunk in self.truncate_message(self.format_message(content)):
- try:
- if reply_to and reply_to.isdigit() and reply_to != "0":
- try:
- result = await self._app.reply(chat_id, reply_to, chunk)
- except Exception as reply_err:
- # Group chats 400 on threaded sends; the SDK has no typed HTTP errors → fall back on any.
- logger.debug("Teams reply() failed, falling back to flat send: %s", reply_err)
- result = await self._app.send(chat_id, chunk)
- else:
- result = await self._app.send(chat_id, chunk)
- last_message_id = getattr(result, "id", None)
- self._remember_sent(result)
- except Exception as e:
- return SendResult(success=False, error=str(e), retryable=True)
- return SendResult(success=True, message_id=last_message_id)
- async def send_typing(self, chat_id: str, metadata: Optional[dict[str, Any]] = None) -> None:
- if self._app:
- with suppress(Exception):
- await self._app.send(chat_id, TypingActivityInput())
- async def _send_media_attachment(
- self, chat_id: str, source: str, default_mime: str, caption: Optional[str] = None, media_label: str = "media"
- ) -> SendResult:
- """Send any media file/URL as a Teams attachment (shared by send_image/video/voice/document).
- Remote ``http(s)://`` URLs are attached by reference; local paths (optional ``file://`` prefix)
- are base64-encoded into a data URI. MIME is guessed from the path, else ``default_mime``."""
- if not self._app:
- return SendResult(success=False, error="Teams app not initialized")
- try:
- import base64
- import mimetypes
- from microsoft_teams.api import Attachment, MessageActivityInput
- if source.startswith(("http://", "https://")):
- content_url = source
- mime_type = mimetypes.guess_type(source.split("?")[0])[0] or default_mime
- else:
- path = source.removeprefix("file://")
- mime_type = mimetypes.guess_type(path)[0] or default_mime
- data = await asyncio.to_thread(Path(path).read_bytes)
- content_url = f"data:{mime_type};base64,{base64.b64encode(data).decode()}"
- activity = MessageActivityInput().add_attachments(Attachment(content_type=mime_type, content_url=content_url))
- if caption:
- activity = activity.add_text(caption)
- result = await self._send_via_conv_ref(chat_id, activity, activity)
- return SendResult(success=True, message_id=getattr(result, "id", None))
- except Exception as e:
- logger.error("[teams] send_%s failed: %s", media_label, e, exc_info=True)
- return SendResult(success=False, error=str(e), retryable=True)
- async def send_image(self, chat_id: str, image_url: str, caption: Optional[str] = None, reply_to: Optional[str] = None,
- metadata: Optional[dict[str, Any]] = None) -> SendResult:
- return await self._send_media_attachment(chat_id, image_url, "image/png", caption=caption, media_label="image")
- async def send_image_file(self, chat_id: str, image_path: str, caption: Optional[str] = None,
- reply_to: Optional[str] = None, **kwargs) -> SendResult:
- return await self.send_image(chat_id=chat_id, image_url=image_path, caption=caption, reply_to=reply_to)
- async def send_video(self, chat_id: str, video_path: str, caption: Optional[str] = None, reply_to: Optional[str] = None,
- metadata: Optional[dict[str, Any]] = None, **kwargs) -> SendResult:
- return await self._send_media_attachment(chat_id, video_path, "video/mp4", caption=caption, media_label="video")
- async def send_voice(self, chat_id: str, audio_path: str, caption: Optional[str] = None, reply_to: Optional[str] = None,
- metadata: Optional[dict[str, Any]] = None, **kwargs) -> SendResult:
- return await self._send_media_attachment(chat_id, audio_path, "audio/mpeg", caption=caption, media_label="voice")
- async def send_document(self, chat_id: str, file_path: str, caption: Optional[str] = None, file_name: Optional[str] = None,
- reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None, **kwargs) -> SendResult:
- return await self._send_media_attachment(
- chat_id, file_path, "application/octet-stream", caption=caption, media_label="document")
- async def get_chat_info(self, chat_id: str) -> dict:
- return {"name": chat_id, "type": "unknown", "chat_id": chat_id}
- _SETUP_CREDENTIALS = (
- ("Client ID", "TEAMS_CLIENT_ID", {}),
- ("Client secret", "TEAMS_CLIENT_SECRET", {"password": True}),
- ("Tenant ID", "TEAMS_TENANT_ID", {}))
- _SETUP_INTRO = ( # "" → blank line
- "You'll need the Teams CLI. If you haven't already:", " npm install -g @microsoft/teams.cli@preview",
- " teams login", "", "Then expose port 3978 publicly (devtunnel / ngrok / cloudflared),", "and create your bot:",
- ' teams app create --name "Hermes" --endpoint "https://<tunnel>/api/messages"', "",
- "The CLI will print CLIENT_ID, CLIENT_SECRET, and TENANT_ID. Paste them below.", "")
- def interactive_setup() -> None:
- from hermes_cli.config import get_env_value, save_env_value
- from hermes_cli.cli_output import prompt, prompt_yes_no, print_info, print_success, print_warning
- from hermes_cli.setup_platforms import declines_reconfigure
- if declines_reconfigure("Teams", "Reconfigure Teams?", "TEAMS_CLIENT_ID"):
- return
- for line in _SETUP_INTRO:
- print_info(line) if line else print()
- for label, env_key, prompt_kwargs in _SETUP_CREDENTIALS:
- value = prompt(label, default=get_env_value(env_key) or "", **prompt_kwargs)
- if not value:
- print_warning(f"{label} is required — skipping Teams setup")
- return
- save_env_value(env_key, value.strip())
- print()
- print_info("To find your AAD object ID for the allowlist: teams status --verbose")
- if prompt_yes_no("Restrict access to specific users? (recommended)", True):
- allowed = prompt("Allowed AAD object IDs (comma-separated)", default=get_env_value("TEAMS_ALLOWED_USERS") or "")
- if allowed:
- save_env_value("TEAMS_ALLOWED_USERS", allowed.replace(" ", ""))
- print_success("Allowlist configured")
- else:
- save_env_value("TEAMS_ALLOWED_USERS", "")
- else:
- save_env_value("TEAMS_ALLOW_ALL_USERS", "true")
- print_warning("⚠️ Open access — anyone who can message the bot can command it.")
- print()
- print_success("Teams configuration saved to ~/.hermes/.env")
- print_info("Install the app in Teams: teams app install --id <teamsAppId>")
- print_info("Restart the gateway: hermes gateway restart")
- def _install_hint() -> str:
- """Point to the setup flow that requests PM's declared Teams extra."""
- return "Teams SDK missing — run `hermes setup`, configure Teams, then restart the gateway"
- def register(ctx) -> None:
- ctx.register_platform(
- name="teams", label="Microsoft Teams", adapter_factory=lambda cfg: TeamsAdapter(cfg),
- dashboard_description="Connect Hermes to Microsoft Teams chats via the Bot Framework.",
- docs_url="https://hermes-agent.nousresearch.com/docs/user-guide/messaging/teams",
- check_fn=check_requirements, # PASSIVE probe — never installs
- ensure_deps_fn=check_teams_requirements, # ACTIVE lazy-installer, run by create_adapter()
- validate_config=validate_config, is_connected=is_connected,
- required_env=["TEAMS_CLIENT_ID", "TEAMS_CLIENT_SECRET", "TEAMS_TENANT_ID"],
- install_hint=_install_hint(), setup_fn=interactive_setup,
- env_enablement_fn=_env_enablement, # env-only setups show up in gateway status
- cron_deliver_env_var="TEAMS_HOME_CHANNEL", # deliver=teams cron home-channel routing
- standalone_sender_fn=_standalone_send, # out-of-process cron delivery via Bot Framework REST
- allowed_users_env="TEAMS_ALLOWED_USERS", allow_all_env="TEAMS_ALLOW_ALL_USERS",
- max_message_length=28000, # Teams supports up to ~28 KB per message
- emoji="💼", allow_update_command=True,
- platform_hint=(
- "You are chatting via Microsoft Teams. Teams renders a subset of "
- "markdown — bold (**text**), italic (*text*), and inline code "
- "(`code`) work, but complex tables or raw HTML do not. Keep "
- "responses clear and professional."))
|