Hermes-agent

plugins/platforms/discord/__init__.py

@@ -0,0 +1,3 @@
+from .adapter import register
+
+__all__ = ["register"]

plugins/platforms/discord/plugin.yaml

@@ -0,0 +1,34 @@
+name: discord-platform
+label: Discord
+kind: platform
+version: 1.0.0
+description: >
+  Discord gateway adapter for Hermes Agent.
+  Connects to Discord via the discord.py library and relays messages
+  between Discord guilds/DMs and the Hermes agent. Supports voice mode,
+  slash commands, free-response channels, role-based DM auth, threads,
+  reactions, and channel skill bindings.
+author: NousResearch
+requires_env:
+  - name: DISCORD_BOT_TOKEN
+    description: "Discord bot token"
+    prompt: "Discord bot token"
+    url: "https://discord.com/developers/applications"
+    password: true
+optional_env:
+  - name: DISCORD_ALLOWED_USERS
+    description: "Comma-separated Discord user IDs allowed to talk to the bot"
+    prompt: "Allowed users (comma-separated)"
+    password: false
+  - name: DISCORD_ALLOW_ALL_USERS
+    description: "Allow any Discord user to trigger the bot (dev only)"
+    prompt: "Allow all users? (true/false)"
+    password: false
+  - name: DISCORD_HOME_CHANNEL
+    description: "Default channel ID for cron / notification delivery"
+    prompt: "Home channel ID"
+    password: false
+  - name: DISCORD_HOME_CHANNEL_NAME
+    description: "Display name for the Discord home channel"
+    prompt: "Home channel display name"
+    password: false

plugins/platforms/discord/voice_mixer.py

@@ -0,0 +1,379 @@
+from __future__ import annotations
+
+"""
+Continuous PCM audio mixer for Discord voice channels.
+
+discord.py (Rapptz) ships no audio mixer: ``VoiceClient.play()`` accepts a
+single :class:`discord.AudioSource` and raises ``ClientException`` if called
+while already playing.  One opus stream per connection, one source feeding it.
+
+This module adds software mixing *upstream* of that single stream.  A
+:class:`VoiceMixer` is itself a ``discord.AudioSource`` that discord.py polls
+every 20 ms via :meth:`read`.  Internally it sums the 20 ms PCM frames of any
+number of child sources, clamps to int16, and returns one blended frame.
+discord.py never knows several streams were combined underneath — it just
+encodes and sends the single mixed frame.
+
+This gives us, for one voice connection at once:
+
+  * an always-on low-volume **ambient/idle loop** (the "thinking" sound),
+  * a **speech** channel (TTS replies, verbal acknowledgements) that plays
+    *over* the ambient bed, automatically **ducking** the ambient gain down
+    while speech is active and restoring it when speech ends — the smooth
+    Grok-voice-mode feel, instead of stop-and-swap.
+
+Design notes
+------------
+* The mixer is installed **once** per guild on join (``vc.play(mixer)``) and
+  runs continuously until the bot leaves.  Children come and go; the mixer
+  itself never stops, so there is no ``is_playing()`` race between an
+  acknowledgement and the final reply.
+* Frame format is Discord-native: 48 kHz, 2 channels, signed 16-bit LE,
+  20 ms per frame == ``discord.opus.Encoder.FRAME_SIZE`` bytes
+  (3840 = 960 samples * 2 channels * 2 bytes).
+* Mixing is a single vectorised int32 add + clip per 20 ms frame (numpy,
+  already a core dependency).  CPU cost is negligible.
+* :meth:`read` is called from discord.py's audio sender **thread**, while
+  children are added/removed from the asyncio event loop thread, so all
+  shared state is guarded by a plain ``threading.Lock``.
+
+The mixer NEVER touches the inbound receive path: it only produces the bot's
+*outgoing* stream.  The :class:`VoiceReceiver` decodes incoming SSRCs only, so
+the mixer's output cannot echo back into transcription.
+"""
+
+import logging
+import threading
+from typing import TYPE_CHECKING, List, Optional
+
+if TYPE_CHECKING:  # numpy is an optional ("voice" extra) dep — never import at runtime top-level
+    import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+def _require_numpy():
+    """Import numpy lazily.
+
+    numpy ships in the optional ``voice`` extra, not the base install, so this
+    module must import cleanly without it (the Discord adapter imports this
+    file unconditionally).  Callers that actually mix audio call this; if the
+    voice extra isn't installed they get a clear error instead of a top-level
+    ImportError that would break the whole adapter import.
+    """
+    import numpy as np  # noqa: PLC0415 — intentional lazy import
+    return np
+
+# Discord-native frame geometry (matches discord.opus.Encoder).
+SAMPLE_RATE = 48000
+CHANNELS = 2
+SAMPLE_WIDTH = 2                       # bytes per sample (s16)
+FRAME_LENGTH_MS = 20
+SAMPLES_PER_FRAME = SAMPLE_RATE * FRAME_LENGTH_MS // 1000   # 960
+FRAME_SIZE = SAMPLES_PER_FRAME * CHANNELS * SAMPLE_WIDTH    # 3840 bytes
+SILENCE_FRAME = b"\x00" * FRAME_SIZE
+
+
+class MixerChild:
+    """A single audio stream feeding into :class:`VoiceMixer`.
+
+    Wraps raw 48 kHz / stereo / s16le PCM bytes.  ``read_frame`` hands back one
+    20 ms frame at a time, optionally looping, with a per-child gain applied.
+    """
+
+    __slots__ = (
+        "name", "_pcm", "_pos", "loop", "gain",
+        "is_speech", "fade_frames", "_fade_done", "_finished",
+    )
+
+    def __init__(
+        self,
+        name: str,
+        pcm: bytes,
+        *,
+        loop: bool = False,
+        gain: float = 1.0,
+        is_speech: bool = False,
+        fade_in_ms: int = 0,
+    ):
+        # Pad to a whole number of frames so looping is seamless and the final
+        # partial frame doesn't click.
+        remainder = len(pcm) % FRAME_SIZE
+        if remainder:
+            pcm = pcm + b"\x00" * (FRAME_SIZE - remainder)
+        self.name = name
+        self._pcm = pcm
+        self._pos = 0
+        self.loop = loop
+        self.gain = float(gain)
+        self.is_speech = is_speech
+        # Linear fade-in over N frames avoids a click when a loud child starts.
+        self.fade_frames = max(0, fade_in_ms // FRAME_LENGTH_MS)
+        self._fade_done = 0
+        self._finished = False
+
+    @property
+    def finished(self) -> bool:
+        return self._finished
+
+    def read_frame(self) -> "Optional[np.ndarray]":
+        """Return the next 20 ms frame as an int16 ndarray, or None if done."""
+        if self._finished:
+            return None
+        if self._pos >= len(self._pcm):
+            if self.loop and self._pcm:
+                self._pos = 0
+            else:
+                self._finished = True
+                return None
+
+        np = _require_numpy()
+        chunk = self._pcm[self._pos:self._pos + FRAME_SIZE]
+        self._pos += FRAME_SIZE
+        if len(chunk) < FRAME_SIZE:
+            chunk = chunk + b"\x00" * (FRAME_SIZE - len(chunk))
+
+        samples = np.frombuffer(chunk, dtype=np.int16).astype(np.float32)
+
+        gain = self.gain
+        if self.fade_frames and self._fade_done < self.fade_frames:
+            self._fade_done += 1
+            gain *= self._fade_done / self.fade_frames
+
+        if gain != 1.0:
+            samples = samples * gain
+        return samples
+
+
+class VoiceMixer:
+    """A continuous ``discord.AudioSource`` that mixes N child streams.
+
+    Use :meth:`set_ambient` to install/replace the looping idle bed and
+    :meth:`play_speech` to layer a one-shot clip over it (ducking the ambient
+    while it plays).  Both are safe to call from the asyncio loop thread while
+    discord.py drains :meth:`read` from its sender thread.
+    """
+
+    # discord.AudioSource subclasses set is_opus()==False to receive PCM.
+    def is_opus(self) -> bool:  # pragma: no cover - trivial
+        return False
+
+    def __init__(
+        self,
+        *,
+        ambient_gain: float = 0.18,
+        duck_gain: float = 0.06,
+        speech_gain: float = 1.0,
+        duck_release_ms: int = 400,
+    ):
+        self._lock = threading.Lock()
+        self._ambient: Optional[MixerChild] = None
+        self._speech: List[MixerChild] = []
+        self._ambient_gain = float(ambient_gain)
+        self._duck_gain = float(duck_gain)
+        self._speech_gain = float(speech_gain)
+        # When speech ends, ramp the ambient back up over this many frames
+        # instead of jumping, so the bed swells back smoothly.
+        self._duck_release_frames = max(1, duck_release_ms // FRAME_LENGTH_MS)
+        self._duck_release_left = 0
+        self._closed = False
+        # Tracks whether speech is currently active, for external callers that
+        # want to avoid double-ducking or know when a reply is mid-flight.
+        self._speech_active = False
+
+    # ------------------------------------------------------------------
+    # Ambient (idle / "thinking") bed
+    # ------------------------------------------------------------------
+
+    def set_ambient(self, pcm: Optional[bytes], *, gain: Optional[float] = None) -> None:
+        """Install (or clear, with ``pcm=None``) the looping ambient bed."""
+        with self._lock:
+            if gain is not None:
+                self._ambient_gain = float(gain)
+            if not pcm:
+                self._ambient = None
+                return
+            self._ambient = MixerChild(
+                "ambient", pcm, loop=True,
+                gain=self._effective_ambient_gain(), fade_in_ms=200,
+            )
+
+    def _effective_ambient_gain(self) -> float:
+        return self._duck_gain if self._speech_active else self._ambient_gain
+
+    # ------------------------------------------------------------------
+    # Speech (TTS replies, verbal acks) layered over the ambient bed
+    # ------------------------------------------------------------------
+
+    def play_speech(self, pcm: bytes, *, gain: Optional[float] = None,
+                    fade_in_ms: int = 40) -> None:
+        """Layer a one-shot speech clip over the ambient bed (ducks ambient)."""
+        if not pcm:
+            return
+        with self._lock:
+            child = MixerChild(
+                "speech", pcm, loop=False,
+                gain=self._speech_gain if gain is None else float(gain),
+                is_speech=True, fade_in_ms=fade_in_ms,
+            )
+            self._speech.append(child)
+            self._speech_active = True
+            self._duck_release_left = 0
+            if self._ambient is not None:
+                self._ambient.gain = self._duck_gain
+
+    @property
+    def speech_active(self) -> bool:
+        with self._lock:
+            return self._speech_active
+
+    def stop_speech(self) -> None:
+        """Drop any in-flight speech immediately and release the duck."""
+        with self._lock:
+            self._speech.clear()
+            self._begin_duck_release_locked()
+
+    def _begin_duck_release_locked(self) -> None:
+        self._speech_active = False
+        self._duck_release_left = self._duck_release_frames
+
+    # ------------------------------------------------------------------
+    # AudioSource interface — called from discord.py's sender thread
+    # ------------------------------------------------------------------
+
+    def read(self) -> bytes:
+        """Return one 20 ms mixed PCM frame (always FRAME_SIZE bytes).
+
+        Returning a non-empty frame keeps discord.py's player alive; we never
+        return b"" because that would stop the single underlying stream and we
+        want the mixer to run continuously for the lifetime of the connection.
+        """
+        with self._lock:
+            if self._closed:
+                return SILENCE_FRAME
+
+            np = _require_numpy()
+            acc: "Optional[np.ndarray]" = None
+
+            # Speech children (drop exhausted ones; release duck when last ends)
+            if self._speech:
+                still_live: List[MixerChild] = []
+                for child in self._speech:
+                    frame = child.read_frame()
+                    if frame is None:
+                        continue
+                    acc = frame if acc is None else acc + frame
+                    still_live.append(child)
+                self._speech = still_live
+                if not self._speech and self._speech_active:
+                    self._begin_duck_release_locked()
+
+            # Ambient bed — ramp gain back up during duck-release.
+            if self._ambient is not None:
+                if self._duck_release_left > 0 and not self._speech_active:
+                    self._duck_release_left -= 1
+                    frac = 1.0 - (self._duck_release_left / self._duck_release_frames)
+                    self._ambient.gain = (
+                        self._duck_gain
+                        + (self._ambient_gain - self._duck_gain) * frac
+                    )
+                elif not self._speech_active and self._duck_release_left == 0:
+                    self._ambient.gain = self._ambient_gain
+                amb = self._ambient.read_frame()
+                if amb is not None:
+                    acc = amb if acc is None else acc + amb
+
+            if acc is None:
+                return SILENCE_FRAME
+
+            np.clip(acc, -32768, 32767, out=acc)
+            return acc.astype(np.int16).tobytes()
+
+    def cleanup(self) -> None:  # called by discord.py when playback stops
+        with self._lock:
+            self._closed = True
+            self._ambient = None
+            self._speech.clear()
+
+
+# ----------------------------------------------------------------------
+# PCM helpers
+# ----------------------------------------------------------------------
+
+def decode_to_pcm(path: str, *, timeout: float = 30.0) -> Optional[bytes]:
+    """Decode any audio file to 48 kHz / stereo / s16le PCM via ffmpeg.
+
+    Returns the raw PCM bytes, or None on failure.  ffmpeg is already a hard
+    requirement of the voice path (see ``VoiceReceiver.pcm_to_wav``).
+    """
+    import subprocess
+
+    try:
+        proc = subprocess.run(
+            [
+                "ffmpeg", "-y", "-loglevel", "error",
+                "-i", path,
+                "-f", "s16le",
+                "-ar", str(SAMPLE_RATE),
+                "-ac", str(CHANNELS),
+                "pipe:1",
+            ],
+            capture_output=True,
+            timeout=timeout,
+            stdin=subprocess.DEVNULL,
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError) as e:
+        logger.warning("decode_to_pcm failed for %s: %s", path, e)
+        return None
+    if proc.returncode != 0:
+        logger.warning(
+            "ffmpeg decode failed for %s (rc=%d): %s",
+            path, proc.returncode, (proc.stderr or b"").decode("utf-8", "replace")[:200],
+        )
+        return None
+    return proc.stdout or None
+
+
+def synth_ambient_pcm(seconds: float = 4.0) -> bytes:
+    """Synthesise a subtle looping ambient bed (no asset file required).
+
+    A soft, slowly-pulsing low pad: two detuned sine partials with a gentle
+    tremolo, plus a touch of filtered noise.  Designed to loop seamlessly
+    (whole number of cycles, zero-crossing endpoints) and sit quietly under
+    speech.  Mono content duplicated to stereo.
+    """
+    np = _require_numpy()
+    n = int(SAMPLE_RATE * seconds)
+    t = np.arange(n, dtype=np.float64) / SAMPLE_RATE
+
+    # Choose base frequencies that complete whole cycles over the loop so the
+    # wrap point is click-free.
+    def _whole_cycle_freq(target: float) -> float:
+        cycles = max(1, round(target * seconds))
+        return cycles / seconds
+
+    f1 = _whole_cycle_freq(110.0)
+    f2 = _whole_cycle_freq(110.5)
+    trem = _whole_cycle_freq(0.5)   # ~0.5 Hz tremolo
+
+    pad = (
+        0.55 * np.sin(2 * np.pi * f1 * t)
+        + 0.45 * np.sin(2 * np.pi * f2 * t)
+    )
+    tremolo = 0.6 + 0.4 * (0.5 * (1 + np.sin(2 * np.pi * trem * t)))
+    signal = pad * tremolo
+
+    # Smooth filtered noise for air, kept very low.
+    rng = np.random.default_rng(7)
+    noise = rng.standard_normal(n)
+    kernel = np.ones(64) / 64.0
+    noise = np.convolve(noise, kernel, mode="same")
+    signal = signal + 0.08 * noise
+
+    # Normalise to a modest peak (mixer applies the real ambient gain on top).
+    peak = float(np.max(np.abs(signal))) or 1.0
+    signal = (signal / peak) * 0.5
+
+    mono16 = (signal * 32767.0).astype(np.int16)
+    stereo16 = np.repeat(mono16[:, None], CHANNELS, axis=1).reshape(-1)
+    return stereo16.tobytes()

plugins/platforms/google_chat/__init__.py

@@ -0,0 +1,3 @@
+from .adapter import register
+
+__all__ = ["register"]

plugins/platforms/google_chat/oauth.py

@@ -0,0 +1,667 @@
+"""User OAuth helper for the Google Chat gateway adapter.
+
+Google Chat's ``media.upload`` REST endpoint hard-rejects service-account
+authentication:
+
+    "This method doesn't support app authentication with a service
+     account. Authenticate with a user account."
+
+(See https://developers.google.com/workspace/chat/api/reference/rest/v1/media/upload
+and https://developers.google.com/chat/api/guides/auth/users.)
+
+For the bot to deliver native file attachments — the same drag-and-drop
+file widget the user gets when they upload manually — each user must
+grant the bot the ``chat.messages.create`` scope ONCE in their own DM.
+The bot stores per-user refresh tokens and calls ``media.upload`` plus
+the subsequent ``messages.create`` *as the requesting user* whenever a
+file needs sending.
+
+This module is BOTH a CLI tool (driven by the agent via slash commands or
+terminal commands) AND a library imported by ``google_chat.py``:
+
+    Library functions (called from the adapter at runtime):
+        load_user_credentials(email=None) -> Credentials | None
+        refresh_or_none(creds, email=None) -> Credentials | None
+        build_user_chat_service(creds) -> chat_v1.Resource
+        list_authorized_emails() -> List[str]
+
+    CLI commands (driven by the agent through the /setup-files slash
+    command, modeled on skills/productivity/google-workspace/scripts/setup.py):
+        --check                          Exit 0 if auth is valid, else 1
+        --client-secret /path/to.json    Persist OAuth client credentials
+        --auth-url                       Print the OAuth URL for the user
+        --auth-code CODE                 Exchange auth code for token
+        --revoke                         Revoke and delete stored token
+        --install-deps                   Install Python dependencies
+        --email EMAIL                    Scope CLI ops to a specific user
+                                         (defaults to legacy single-user
+                                         mode when omitted)
+
+The flow mirrors the existing google-workspace skill exactly so anyone
+familiar with that flow can read this without surprises.
+
+Token storage layout
+--------------------
+- Per-user tokens (keyed by sender email):
+    ``${HERMES_HOME}/google_chat_user_tokens/<sanitized_email>.json``
+- Legacy single-user token (fallback, untouched for backward compat):
+    ``${HERMES_HOME}/google_chat_user_token.json``
+- Per-user pending OAuth state during /setup-files start → exchange:
+    ``${HERMES_HOME}/google_chat_user_oauth_pending/<sanitized_email>.json``
+- Legacy pending state:
+    ``${HERMES_HOME}/google_chat_user_oauth_pending.json``
+- OAuth client secret (profile-scoped — each profile registers its own):
+    ``${HERMES_HOME}/google_chat_user_client_secret.json``
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import re
+import secrets
+import stat
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, List, Optional, Tuple
+
+# Pin the legacy logger name so operator-side log filters keep matching
+# after the in-tree → plugin migration. See adapter.py for context.
+logger = logging.getLogger("gateway.platforms.google_chat_user_oauth")
+
+# Use the project's HERMES_HOME helper so the token follows the user's
+# profile (e.g. tests can override via HERMES_HOME=/tmp/...).
+try:
+    from hermes_constants import display_hermes_home, get_hermes_home
+except (ModuleNotFoundError, ImportError):
+    # Fallback for environments where hermes_constants isn't importable
+    # (mirrors the same fallback used by the google-workspace skill's
+    # _hermes_home.py shim).
+    def get_hermes_home() -> Path:
+        val = os.environ.get("HERMES_HOME", "").strip()
+        return Path(val) if val else Path.home() / ".hermes"
+
+    def display_hermes_home() -> str:
+        home = get_hermes_home()
+        try:
+            return "~/" + str(home.relative_to(Path.home()))
+        except ValueError:
+            return str(home)
+
+from utils import atomic_replace
+
+
+def _hermes_home() -> Path:
+    """Resolve HERMES_HOME at call time (NOT module import).
+
+    Tests and ``HERMES_HOME=...`` env overrides need this to be late-
+    binding. If we cached the path at import time, switching profiles
+    or tweaking env vars in tests would silently keep using the old
+    path."""
+    return get_hermes_home()
+
+
+# Filesystem-safe key: lowercase, allow ``[a-z0-9._-@]``, replace anything
+# else with ``_``. ``ramon.fernandez@nttdata.com`` stays human-readable
+# (``ramon.fernandez@nttdata.com.json``) which makes admin debugging by
+# ``ls ~/.hermes/google_chat_user_tokens/`` trivial.
+_EMAIL_FS_RE = re.compile(r"[^a-z0-9._@-]+")
+
+
+def _sanitize_email(email: str) -> str:
+    cleaned = _EMAIL_FS_RE.sub("_", (email or "").strip().lower())
+    return cleaned or "_unknown_"
+
+
+def _legacy_token_path() -> Path:
+    return _hermes_home() / "google_chat_user_token.json"
+
+
+def _user_tokens_dir() -> Path:
+    return _hermes_home() / "google_chat_user_tokens"
+
+
+def _legacy_pending_path() -> Path:
+    return _hermes_home() / "google_chat_user_oauth_pending.json"
+
+
+def _user_pending_dir() -> Path:
+    return _hermes_home() / "google_chat_user_oauth_pending"
+
+
+def _token_path(email: Optional[str] = None) -> Path:
+    """Return the on-disk token path for ``email`` or the legacy path."""
+    if email:
+        return _user_tokens_dir() / f"{_sanitize_email(email)}.json"
+    return _legacy_token_path()
+
+
+def _client_secret_path() -> Path:
+    return _hermes_home() / "google_chat_user_client_secret.json"
+
+
+def _pending_auth_path(email: Optional[str] = None) -> Path:
+    if email:
+        return _user_pending_dir() / f"{_sanitize_email(email)}.json"
+    return _legacy_pending_path()
+
+
+# Minimum scope for native Chat attachment delivery.
+# `chat.messages.create` covers BOTH `media.upload` and the subsequent
+# `messages.create` that references the attachmentDataRef. We deliberately
+# do NOT request drive.file or other scopes — least privilege.
+SCOPES: List[str] = [
+    "https://www.googleapis.com/auth/chat.messages.create",
+]
+
+# Pip packages required for the OAuth flow.
+_REQUIRED_PACKAGES = [
+    "google-api-python-client",
+    "google-auth-oauthlib",
+    "google-auth-httplib2",
+]
+
+# Out-of-band redirect: Google deprecated the ``urn:ietf:wg:oauth:2.0:oob``
+# flow, so we use a localhost redirect that's expected to FAIL. The user
+# copies the auth code from the failed browser URL bar back into chat.
+# Same trick used by skills/productivity/google-workspace/scripts/setup.py.
+_REDIRECT_URI = "http://localhost:1"
+
+
+# =============================================================================
+# Library API — called from the adapter at runtime
+# =============================================================================
+
+
+def load_user_credentials(email: Optional[str] = None) -> Optional[Any]:
+    """Load + validate persisted user OAuth credentials.
+
+    ``email`` selects the per-user token file; ``None`` falls back to the
+    legacy single-user path (left in place for installs that ran the
+    pre-multi-user flow). Returns a ``google.oauth2.credentials.Credentials``
+    instance ready for use, or ``None`` if no token is stored, the token
+    is corrupt, or refresh fails. Adapter callers should treat ``None``
+    as "user has not run /setup-files yet" and surface the setup-instructions
+    fallback to the user.
+
+    Does NOT raise on the no-token case — that's expected.
+    """
+    token_path = _token_path(email)
+    if not token_path.exists():
+        return None
+
+    try:
+        from google.oauth2.credentials import Credentials
+        from google.auth.transport.requests import Request
+    except ImportError:
+        logger.warning(
+            "[google_chat_user_oauth] google-auth not installed; user-OAuth "
+            "attachment delivery is disabled. Install hermes-agent[google_chat]."
+        )
+        return None
+
+    try:
+        # Don't pass scopes — user may have authorized only a subset, and
+        # passing scopes makes refresh validate them strictly. Same logic
+        # as the google-workspace skill.
+        creds = Credentials.from_authorized_user_file(str(token_path))
+    except Exception as exc:
+        logger.warning(
+            "[google_chat_user_oauth] token at %s is corrupt: %s",
+            token_path, exc,
+        )
+        return None
+
+    if creds.valid:
+        return creds
+
+    if creds.expired and creds.refresh_token:
+        try:
+            creds.refresh(Request())
+        except Exception as exc:
+            logger.warning(
+                "[google_chat_user_oauth] token refresh failed (user "
+                "should re-run /setup-files): %s", exc,
+            )
+            return None
+        # Persist refreshed token so next start picks up the new access
+        # token without an unnecessary refresh round-trip.
+        _persist_credentials(creds, token_path)
+        return creds
+
+    # Token exists but is unusable (e.g. revoked, no refresh token).
+    return None
+
+
+def refresh_or_none(creds: Any, email: Optional[str] = None) -> Optional[Any]:
+    """Refresh ``creds`` if expired. Returns the credentials or ``None``.
+
+    Used by the adapter just before calling media.upload to ensure the
+    token is current. Returns ``None`` if refresh fails — caller falls
+    back to the text-notice path. ``email`` controls where the refreshed
+    token is written back; ``None`` keeps the legacy single-file path.
+    """
+    if creds is None:
+        return None
+
+    if creds.valid:
+        return creds
+
+    try:
+        from google.auth.transport.requests import Request
+    except ImportError:
+        return None
+
+    if creds.expired and creds.refresh_token:
+        try:
+            creds.refresh(Request())
+            _persist_credentials(creds, _token_path(email))
+            return creds
+        except Exception as exc:
+            logger.warning(
+                "[google_chat_user_oauth] refresh failed: %s", exc,
+            )
+            return None
+
+    return None
+
+
+def build_user_chat_service(creds: Any) -> Any:
+    """Build a Google Chat API client authenticated as the user.
+
+    Used for media.upload + the subsequent messages.create that
+    references the attachmentDataRef. The bot's separate SA-authed
+    client (``self._chat_api`` in the adapter) is for everything else.
+    """
+    from googleapiclient.discovery import build as build_service
+    return build_service("chat", "v1", credentials=creds, cache_discovery=False)
+
+
+def list_authorized_emails() -> List[str]:
+    """Return the set of user emails that have stored per-user tokens.
+
+    Lists files in the per-user tokens dir; does NOT include the legacy
+    single-user token (its owner is unknown). Sanitized filenames lose
+    the ``+suffix`` part of plus-addressed emails — accept that and use
+    this list only for admin display, not for trust decisions.
+    """
+    d = _user_tokens_dir()
+    if not d.exists():
+        return []
+    out: List[str] = []
+    for f in d.iterdir():
+        if f.is_file() and f.suffix == ".json":
+            out.append(f.stem)
+    out.sort()
+    return out
+
+
+def _persist_credentials(creds: Any, token_path: Path) -> None:
+    """Persist refreshed credentials atomically with private permissions."""
+    try:
+        _write_private_json(
+            token_path,
+            _normalize_authorized_user_payload(json.loads(creds.to_json())),
+        )
+    except Exception:
+        logger.debug(
+            "[google_chat_user_oauth] failed to persist credentials at %s",
+            token_path, exc_info=True,
+        )
+
+
+# =============================================================================
+# CLI commands — driven by the agent via /setup-files
+# =============================================================================
+
+
+def _normalize_authorized_user_payload(payload: dict) -> dict:
+    """Ensure the persisted token JSON has the type field google-auth expects."""
+    normalized = dict(payload)
+    if not normalized.get("type"):
+        normalized["type"] = "authorized_user"
+    return normalized
+
+
+def _write_private_json(path: Path, data: Any) -> None:
+    """Atomically write JSON with 0o600 permissions where supported."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(path.parent, 0o700)
+    except OSError:
+        pass
+
+    tmp_path = path.with_suffix(f".tmp.{os.getpid()}.{secrets.token_hex(4)}")
+    try:
+        fd = os.open(
+            str(tmp_path),
+            os.O_WRONLY | os.O_CREAT | os.O_EXCL,
+            stat.S_IRUSR | stat.S_IWUSR,
+        )
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(data, fh, indent=2, ensure_ascii=False)
+            fh.flush()
+            os.fsync(fh.fileno())
+        atomic_replace(tmp_path, path)
+        try:
+            os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)
+        except OSError:
+            pass
+    finally:
+        try:
+            if tmp_path.exists():
+                tmp_path.unlink()
+        except OSError:
+            pass
+
+
+def _ensure_deps() -> None:
+    """Check deps available; install if not; exit on failure."""
+    try:
+        import googleapiclient  # noqa: F401
+        import google_auth_oauthlib  # noqa: F401
+    except ImportError:
+        if not install_deps():
+            sys.exit(1)
+
+
+def install_deps() -> bool:
+    try:
+        import googleapiclient  # noqa: F401
+        import google_auth_oauthlib  # noqa: F401
+        print("Dependencies already installed.")
+        return True
+    except ImportError:
+        pass
+
+    print("Installing Google Chat OAuth dependencies...")
+    try:
+        subprocess.check_call(
+            [sys.executable, "-m", "pip", "install", "--quiet"] + _REQUIRED_PACKAGES,
+            stdout=subprocess.DEVNULL,
+        )
+        print("Dependencies installed.")
+        return True
+    except subprocess.CalledProcessError as exc:
+        print(f"ERROR: Failed to install dependencies: {exc}")
+        print("Or install via the optional extra:")
+        print("  pip install 'hermes-agent[google_chat]'")
+        return False
+
+
+def check_auth(email: Optional[str] = None) -> bool:
+    """Print status; return True if creds are usable.
+
+    Per-user when ``email`` given, legacy single-user when omitted.
+    """
+    token_path = _token_path(email)
+    if not token_path.exists():
+        print(f"NOT_AUTHENTICATED: No token at {token_path}")
+        return False
+
+    creds = load_user_credentials(email)
+    if creds is None:
+        print(f"TOKEN_INVALID: Re-run /setup-files (path: {token_path})")
+        return False
+
+    print(f"AUTHENTICATED: Token valid at {token_path}")
+    return True
+
+
+def store_client_secret(path: str) -> None:
+    """Validate and copy the user's OAuth client_secret.json into HERMES_HOME."""
+    src = Path(path).expanduser().resolve()
+    if not src.exists():
+        print(f"ERROR: File not found: {src}")
+        sys.exit(1)
+
+    try:
+        data = json.loads(src.read_text())
+    except json.JSONDecodeError:
+        print("ERROR: File is not valid JSON.")
+        sys.exit(1)
+
+    if "installed" not in data and "web" not in data:
+        print(
+            "ERROR: Not a Google OAuth client secret file (missing "
+            "'installed' or 'web' key)."
+        )
+        print(
+            "Download from: https://console.cloud.google.com/apis/credentials"
+        )
+        sys.exit(1)
+
+    target = _client_secret_path()
+    _write_private_json(target, data)
+    print(f"OK: Client secret saved to {target}")
+
+
+def _save_pending_auth(*, state: str, code_verifier: str,
+                      email: Optional[str] = None) -> None:
+    pending = _pending_auth_path(email)
+    _write_private_json(
+        pending,
+        {
+            "state": state,
+            "code_verifier": code_verifier,
+            "redirect_uri": _REDIRECT_URI,
+            "email": email or "",
+        },
+    )
+
+
+def _load_pending_auth(email: Optional[str] = None) -> dict:
+    pending = _pending_auth_path(email)
+    if not pending.exists():
+        print("ERROR: No pending OAuth session found. Run --auth-url first.")
+        sys.exit(1)
+    try:
+        data = json.loads(pending.read_text())
+    except Exception as exc:
+        print(f"ERROR: Could not read pending OAuth session: {exc}")
+        print("Run --auth-url again to start a fresh session.")
+        sys.exit(1)
+    if not data.get("state") or not data.get("code_verifier"):
+        print("ERROR: Pending OAuth session is missing PKCE data.")
+        print("Run --auth-url again.")
+        sys.exit(1)
+    return data
+
+
+def _extract_code_and_state(code_or_url: str) -> Tuple[str, Optional[str]]:
+    """Accept a raw auth code OR the full failed-redirect URL the user pastes."""
+    if not code_or_url.startswith("http"):
+        return code_or_url, None
+
+    from urllib.parse import parse_qs, urlparse
+
+    parsed = urlparse(code_or_url)
+    params = parse_qs(parsed.query)
+    if "code" not in params:
+        print("ERROR: No 'code' parameter found in URL.")
+        sys.exit(1)
+    state = params.get("state", [None])[0]
+    return params["code"][0], state
+
+
+def get_auth_url(email: Optional[str] = None) -> None:
+    """Print the OAuth URL for the user to visit. Persists PKCE state.
+
+    ``email`` namespaces the pending state so two users can be mid-flow
+    in parallel without trampling each other's PKCE verifier.
+    """
+    if not _client_secret_path().exists():
+        print("ERROR: No client secret stored. Run --client-secret first.")
+        sys.exit(1)
+
+    _ensure_deps()
+    from google_auth_oauthlib.flow import Flow
+
+    flow = Flow.from_client_secrets_file(
+        str(_client_secret_path()),
+        scopes=SCOPES,
+        redirect_uri=_REDIRECT_URI,
+        autogenerate_code_verifier=True,
+    )
+    auth_url, state = flow.authorization_url(
+        access_type="offline",
+        prompt="consent",
+    )
+    _save_pending_auth(state=state, code_verifier=flow.code_verifier, email=email)
+    print(auth_url)
+
+
+def exchange_auth_code(code: str, email: Optional[str] = None) -> None:
+    """Exchange an auth code (or pasted redirect URL) for a refresh token.
+
+    ``email`` selects the destination token path. ``None`` writes to the
+    legacy single-user path (kept for the existing CLI entrypoint and for
+    pre-multi-user installs).
+    """
+    if not _client_secret_path().exists():
+        print("ERROR: No client secret stored. Run --client-secret first.")
+        sys.exit(1)
+
+    pending_auth = _load_pending_auth(email)
+    raw_callback = code
+    code, returned_state = _extract_code_and_state(code)
+    if returned_state and returned_state != pending_auth["state"]:
+        print(
+            "ERROR: OAuth state mismatch. Run --auth-url again to start a "
+            "fresh session."
+        )
+        sys.exit(1)
+
+    _ensure_deps()
+    from google_auth_oauthlib.flow import Flow
+    from urllib.parse import parse_qs, urlparse
+
+    granted_scopes = list(SCOPES)
+    if isinstance(raw_callback, str) and raw_callback.startswith("http"):
+        params = parse_qs(urlparse(raw_callback).query)
+        scope_val = (params.get("scope") or [""])[0].strip()
+        if scope_val:
+            granted_scopes = scope_val.split()
+
+    flow = Flow.from_client_secrets_file(
+        str(_client_secret_path()),
+        scopes=granted_scopes,
+        redirect_uri=pending_auth.get("redirect_uri", _REDIRECT_URI),
+        state=pending_auth["state"],
+        code_verifier=pending_auth["code_verifier"],
+    )
+
+    try:
+        # Accept partial scopes — user may deselect items in the consent screen.
+        os.environ["OAUTHLIB_RELAX_TOKEN_SCOPE"] = "1"
+        flow.fetch_token(code=code)
+    except Exception as exc:
+        print(f"ERROR: Token exchange failed: {exc}")
+        print("The code may have expired. Run --auth-url to get a fresh URL.")
+        sys.exit(1)
+
+    creds = flow.credentials
+    token_payload = _normalize_authorized_user_payload(json.loads(creds.to_json()))
+
+    actually_granted = (
+        list(creds.granted_scopes or [])
+        if hasattr(creds, "granted_scopes") and creds.granted_scopes
+        else []
+    )
+    if actually_granted:
+        token_payload["scopes"] = actually_granted
+    elif granted_scopes != SCOPES:
+        token_payload["scopes"] = granted_scopes
+
+    token_path = _token_path(email)
+    _write_private_json(token_path, token_payload)
+    _pending_auth_path(email).unlink(missing_ok=True)
+
+    print(f"OK: Authenticated. Token saved to {token_path}")
+    rel_label = (
+        f"{display_hermes_home()}/google_chat_user_tokens/{_sanitize_email(email)}.json"
+        if email
+        else f"{display_hermes_home()}/google_chat_user_token.json"
+    )
+    print(f"Profile path: {rel_label}")
+
+
+def revoke(email: Optional[str] = None) -> None:
+    """Revoke the stored token with Google and delete it locally.
+
+    Per-user when ``email`` given, legacy single-user when omitted.
+    """
+    token_path = _token_path(email)
+    if not token_path.exists():
+        print("No token to revoke.")
+        return
+
+    _ensure_deps()
+    from google.oauth2.credentials import Credentials
+    from google.auth.transport.requests import Request
+
+    try:
+        creds = Credentials.from_authorized_user_file(str(token_path), SCOPES)
+        if creds.expired and creds.refresh_token:
+            creds.refresh(Request())
+
+        import urllib.request
+        urllib.request.urlopen(
+            urllib.request.Request(
+                f"https://oauth2.googleapis.com/revoke?token={creds.token}",
+                method="POST",
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            ),
+            timeout=15,
+        )
+        print("Token revoked with Google.")
+    except Exception as exc:
+        print(f"Remote revocation failed (token may already be invalid): {exc}")
+
+    token_path.unlink(missing_ok=True)
+    _pending_auth_path(email).unlink(missing_ok=True)
+    print(f"Deleted {token_path}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Google Chat user-OAuth setup for Hermes (native attachment delivery)"
+    )
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--check", action="store_true",
+                       help="Check if auth is valid (exit 0=yes, 1=no)")
+    group.add_argument("--client-secret", metavar="PATH",
+                       help="Store OAuth client_secret.json")
+    group.add_argument("--auth-url", action="store_true",
+                       help="Print OAuth URL for user to visit")
+    group.add_argument("--auth-code", metavar="CODE",
+                       help="Exchange auth code for token")
+    group.add_argument("--revoke", action="store_true",
+                       help="Revoke and delete stored token")
+    group.add_argument("--install-deps", action="store_true",
+                       help="Install Python dependencies")
+    parser.add_argument("--email", metavar="EMAIL", default=None,
+                       help="Scope operation to a specific user's token "
+                            "(default: legacy single-user path)")
+    args = parser.parse_args()
+
+    email = args.email or None
+    if args.check:
+        sys.exit(0 if check_auth(email) else 1)
+    elif args.client_secret:
+        store_client_secret(args.client_secret)
+    elif args.auth_url:
+        get_auth_url(email)
+    elif args.auth_code:
+        exchange_auth_code(args.auth_code, email)
+    elif args.revoke:
+        revoke(email)
+    elif args.install_deps:
+        sys.exit(0 if install_deps() else 1)
+
+
+if __name__ == "__main__":
+    main()

plugins/platforms/google_chat/plugin.yaml

@@ -0,0 +1,39 @@
+name: google_chat-platform
+label: Google Chat
+kind: platform
+version: 1.0.0
+description: >
+  Google Chat gateway adapter for Hermes Agent.
+  Connects via Cloud Pub/Sub pull subscription for inbound events and the
+  Google Chat REST API for outbound messages — same ergonomics as Slack
+  Socket Mode or Telegram long-polling, no public URL required. Native
+  file attachments are delivered via per-user OAuth (each user runs
+  /setup-files once in their own DM).
+author: Ramón Fernández
+# ``requires_env`` entries are surfaced in ``hermes config`` UI via the
+# platform-plugin env var injector in ``hermes_cli/config.py``.  Using the
+# rich-dict form lets us contribute description/url/prompt metadata so users
+# see helpful guidance instead of the auto-generated fallback text.
+requires_env:
+  - name: GOOGLE_CHAT_PROJECT_ID
+    description: "GCP project ID hosting the Pub/Sub topic for Chat events. Falls back to GOOGLE_CLOUD_PROJECT."
+    prompt: "GCP project ID"
+    url: "https://console.cloud.google.com/"
+    password: false
+  - name: GOOGLE_CHAT_SUBSCRIPTION_NAME
+    description: "Full Pub/Sub subscription path: projects/<proj>/subscriptions/<sub>. Legacy alias: GOOGLE_CHAT_SUBSCRIPTION."
+    prompt: "Pub/Sub subscription name"
+    password: false
+  - name: GOOGLE_CHAT_SERVICE_ACCOUNT_JSON
+    description: "Path to Service Account JSON key (or inline JSON). Leave empty to use Application Default Credentials on Cloud Run / GCE. Falls back to GOOGLE_APPLICATION_CREDENTIALS."
+    prompt: "Path to SA JSON (or empty for ADC)"
+    password: true
+optional_env:
+  - name: GOOGLE_CHAT_ALLOWED_USERS
+    description: "Comma-separated user emails allowed to interact with the bot."
+    prompt: "Allowed user emails (comma-separated)"
+    password: false
+  - name: GOOGLE_CHAT_HOME_CHANNEL
+    description: "Default space for cron / notification delivery (e.g. spaces/AAAA...)."
+    prompt: "Home space ID (or empty)"
+    password: false

plugins/platforms/homeassistant/__init__.py

@@ -0,0 +1,3 @@
+from .adapter import register
+
+__all__ = ["register"]

plugins/platforms/homeassistant/adapter.py

@@ -0,0 +1,577 @@
+"""
+Home Assistant platform adapter.
+
+Connects to the HA WebSocket API for real-time event monitoring.
+State-change events are converted to MessageEvent objects and forwarded
+to the agent for processing.  Outbound messages are delivered as HA
+persistent notifications.
+
+Requires:
+- aiohttp (already in messaging extras)
+- HASS_TOKEN env var (Long-Lived Access Token)
+- HASS_URL env var (default: http://homeassistant.local:8123)
+"""
+
+import asyncio
+import json
+import logging
+import os
+import time
+import uuid
+from datetime import datetime
+from typing import Any, Dict, Optional, Set
+
+try:
+    import aiohttp
+    AIOHTTP_AVAILABLE = True
+except ImportError:
+    AIOHTTP_AVAILABLE = False
+    aiohttp = None  # type: ignore[assignment]
+
+from gateway.config import Platform, PlatformConfig
+from gateway.platforms.base import (
+    BasePlatformAdapter,
+    MessageEvent,
+    MessageType,
+    SendResult,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def check_ha_requirements() -> bool:
+    """Check if Home Assistant dependencies are available and configured."""
+    if not AIOHTTP_AVAILABLE:
+        return False
+    if not os.getenv("HASS_TOKEN"):
+        return False
+    return True
+
+
+class HomeAssistantAdapter(BasePlatformAdapter):
+    """
+    Home Assistant WebSocket adapter.
+
+    Subscribes to ``state_changed`` events and forwards them as
+    MessageEvent objects.  Supports domain/entity filtering and
+    per-entity cooldowns to avoid event floods.
+    """
+
+    MAX_MESSAGE_LENGTH = 4096
+
+    # Reconnection backoff schedule (seconds)
+    _BACKOFF_STEPS = [5, 10, 30, 60]
+
+    def __init__(self, config: PlatformConfig):
+        super().__init__(config, Platform.HOMEASSISTANT)
+
+        # Connection state
+        self._session: Optional["aiohttp.ClientSession"] = None
+        self._ws: Optional["aiohttp.ClientWebSocketResponse"] = None
+        self._rest_session: Optional["aiohttp.ClientSession"] = None
+        self._listen_task: Optional[asyncio.Task] = None
+        self._msg_id: int = 0
+
+        # Configuration from extra
+        extra = config.extra or {}
+        token = config.token or os.getenv("HASS_TOKEN", "")
+        url = extra.get("url") or os.getenv("HASS_URL", "http://homeassistant.local:8123")
+        self._hass_url: str = url.rstrip("/")
+        self._hass_token: str = token
+
+        # Event filtering
+        self._watch_domains: Set[str] = set(extra.get("watch_domains", []))
+        self._watch_entities: Set[str] = set(extra.get("watch_entities", []))
+        self._ignore_entities: Set[str] = set(extra.get("ignore_entities", []))
+        self._watch_all: bool = bool(extra.get("watch_all", False))
+        self._cooldown_seconds: int = int(extra.get("cooldown_seconds", 30))
+
+        # Cooldown tracking: entity_id -> last_event_timestamp
+        self._last_event_time: Dict[str, float] = {}
+
+    def _next_id(self) -> int:
+        """Return the next WebSocket message ID."""
+        self._msg_id += 1
+        return self._msg_id
+
+    # ------------------------------------------------------------------
+    # Connection lifecycle
+    # ------------------------------------------------------------------
+
+    async def connect(self) -> bool:
+        """Connect to HA WebSocket API and subscribe to events."""
+        if not AIOHTTP_AVAILABLE:
+            logger.warning("[%s] aiohttp not installed. Run: pip install aiohttp", self.name)
+            return False
+
+        if not self._hass_token:
+            logger.warning("[%s] No HASS_TOKEN configured", self.name)
+            return False
+
+        try:
+            success = await self._ws_connect()
+            if not success:
+                return False
+
+            # Dedicated REST session for send() calls
+            self._rest_session = aiohttp.ClientSession(
+                timeout=aiohttp.ClientTimeout(total=30)
+            )
+
+            # Warn if no event filters are configured
+            if not self._watch_domains and not self._watch_entities and not self._watch_all:
+                logger.warning(
+                    "[%s] No watch_domains, watch_entities, or watch_all configured. "
+                    "All state_changed events will be dropped. Configure filters in "
+                    "your HA platform config to receive events.",
+                    self.name,
+                )
+
+            # Start background listener
+            self._listen_task = asyncio.create_task(self._listen_loop())
+            self._running = True
+            logger.info("[%s] Connected to %s", self.name, self._hass_url)
+            return True
+
+        except Exception as e:
+            logger.error("[%s] Failed to connect: %s", self.name, e)
+            return False
+
+    async def _ws_connect(self) -> bool:
+        """Establish WebSocket connection and authenticate."""
+        ws_url = self._hass_url.replace("https://", "wss://").replace("http://", "ws://")
+        ws_url = f"{ws_url}/api/websocket"
+
+        self._session = aiohttp.ClientSession(
+            timeout=aiohttp.ClientTimeout(total=30)
+        )
+        self._ws = await self._session.ws_connect(ws_url, heartbeat=30, timeout=30)
+
+        # Step 1: Receive auth_required
+        msg = await self._ws.receive_json()
+        if msg.get("type") != "auth_required":
+            logger.error("Expected auth_required, got: %s", msg.get("type"))
+            await self._cleanup_ws()
+            return False
+
+        # Step 2: Send auth
+        await self._ws.send_json({
+            "type": "auth",
+            "access_token": self._hass_token,
+        })
+
+        # Step 3: Wait for auth_ok
+        msg = await self._ws.receive_json()
+        if msg.get("type") != "auth_ok":
+            logger.error("Auth failed: %s", msg)
+            await self._cleanup_ws()
+            return False
+
+        # Step 4: Subscribe to state_changed events
+        sub_id = self._next_id()
+        await self._ws.send_json({
+            "id": sub_id,
+            "type": "subscribe_events",
+            "event_type": "state_changed",
+        })
+
+        # Verify subscription acknowledgement
+        msg = await self._ws.receive_json()
+        if not msg.get("success"):
+            logger.error("Failed to subscribe to events: %s", msg)
+            await self._cleanup_ws()
+            return False
+
+        return True
+
+    async def _cleanup_ws(self) -> None:
+        """Close WebSocket and session."""
+        if self._ws and not self._ws.closed:
+            await self._ws.close()
+        self._ws = None
+        if self._session and not self._session.closed:
+            await self._session.close()
+        self._session = None
+
+    async def disconnect(self) -> None:
+        """Disconnect from Home Assistant."""
+        self._running = False
+        if self._listen_task:
+            self._listen_task.cancel()
+            try:
+                await self._listen_task
+            except asyncio.CancelledError:
+                pass
+            self._listen_task = None
+
+        await self._cleanup_ws()
+        if self._rest_session and not self._rest_session.closed:
+            await self._rest_session.close()
+        self._rest_session = None
+        logger.info("[%s] Disconnected", self.name)
+
+    # ------------------------------------------------------------------
+    # Event listener
+    # ------------------------------------------------------------------
+
+    async def _listen_loop(self) -> None:
+        """Main event loop with automatic reconnection."""
+        backoff_idx = 0
+
+        while self._running:
+            try:
+                await self._read_events()
+            except asyncio.CancelledError:
+                return
+            except Exception as e:
+                logger.warning("[%s] WebSocket error: %s", self.name, e)
+
+            if not self._running:
+                return
+
+            # Reconnect with backoff
+            delay = self._BACKOFF_STEPS[min(backoff_idx, len(self._BACKOFF_STEPS) - 1)]
+            logger.info("[%s] Reconnecting in %ds...", self.name, delay)
+            await asyncio.sleep(delay)
+            backoff_idx += 1
+
+            try:
+                await self._cleanup_ws()
+                success = await self._ws_connect()
+                if success:
+                    backoff_idx = 0  # Reset on successful reconnect
+                    logger.info("[%s] Reconnected", self.name)
+            except Exception as e:
+                logger.warning("[%s] Reconnection failed: %s", self.name, e)
+
+    async def _read_events(self) -> None:
+        """Read events from WebSocket until disconnected."""
+        if self._ws is None or self._ws.closed:
+            return
+        async for ws_msg in self._ws:
+            if ws_msg.type == aiohttp.WSMsgType.TEXT:
+                try:
+                    data = json.loads(ws_msg.data)
+                    if data.get("type") == "event":
+                        await self._handle_ha_event(data.get("event", {}))
+                except json.JSONDecodeError:
+                    logger.debug("Invalid JSON from HA WS: %s", ws_msg.data[:200])
+            elif ws_msg.type in {aiohttp.WSMsgType.CLOSED, aiohttp.WSMsgType.ERROR}:
+                break
+
+    async def _handle_ha_event(self, event: Dict[str, Any]) -> None:
+        """Process a state_changed event from Home Assistant."""
+        event_data = event.get("data", {})
+        entity_id: str = event_data.get("entity_id", "")
+
+        if not entity_id:
+            return
+
+        # Apply ignore filter
+        if entity_id in self._ignore_entities:
+            return
+
+        # Apply domain/entity watch filters (closed by default — require
+        # explicit watch_domains, watch_entities, or watch_all to forward)
+        domain = entity_id.split(".")[0] if "." in entity_id else ""
+        if self._watch_domains or self._watch_entities:
+            domain_match = domain in self._watch_domains if self._watch_domains else False
+            entity_match = entity_id in self._watch_entities if self._watch_entities else False
+            if not domain_match and not entity_match:
+                return
+        elif not self._watch_all:
+            # No filters configured and watch_all is off — drop the event
+            return
+
+        # Apply cooldown
+        now = time.time()
+        last = self._last_event_time.get(entity_id, 0)
+        if (now - last) < self._cooldown_seconds:
+            return
+        self._last_event_time[entity_id] = now
+
+        # Build human-readable message
+        old_state = event_data.get("old_state", {})
+        new_state = event_data.get("new_state", {})
+        message = self._format_state_change(entity_id, old_state, new_state)
+
+        if not message:
+            return
+
+        # Build MessageEvent and forward to handler
+        source = self.build_source(
+            chat_id="ha_events",
+            chat_name="Home Assistant Events",
+            chat_type="channel",
+            user_id="homeassistant",
+            user_name="Home Assistant",
+        )
+
+        msg_event = MessageEvent(
+            text=message,
+            message_type=MessageType.TEXT,
+            source=source,
+            message_id=f"ha_{entity_id}_{int(now)}",
+            timestamp=datetime.now(),
+        )
+
+        await self.handle_message(msg_event)
+
+    @staticmethod
+    def _format_state_change(
+        entity_id: str,
+        old_state: Dict[str, Any],
+        new_state: Dict[str, Any],
+    ) -> Optional[str]:
+        """Convert a state_changed event into a human-readable description."""
+        if not new_state:
+            return None
+
+        old_val = old_state.get("state", "unknown") if old_state else "unknown"
+        new_val = new_state.get("state", "unknown")
+
+        # Skip if state didn't actually change
+        if old_val == new_val:
+            return None
+
+        friendly_name = new_state.get("attributes", {}).get("friendly_name", entity_id)
+        domain = entity_id.split(".")[0] if "." in entity_id else ""
+
+        # Domain-specific formatting
+        if domain == "climate":
+            attrs = new_state.get("attributes", {})
+            temp = attrs.get("current_temperature", "?")
+            target = attrs.get("temperature", "?")
+            return (
+                f"[Home Assistant] {friendly_name}: HVAC mode changed from "
+                f"'{old_val}' to '{new_val}' (current: {temp}, target: {target})"
+            )
+
+        if domain == "sensor":
+            unit = new_state.get("attributes", {}).get("unit_of_measurement", "")
+            return (
+                f"[Home Assistant] {friendly_name}: changed from "
+                f"{old_val}{unit} to {new_val}{unit}"
+            )
+
+        if domain == "binary_sensor":
+            return (
+                f"[Home Assistant] {friendly_name}: "
+                f"{'triggered' if new_val == 'on' else 'cleared'} "
+                f"(was {'triggered' if old_val == 'on' else 'cleared'})"
+            )
+
+        if domain in {"light", "switch", "fan"}:
+            return (
+                f"[Home Assistant] {friendly_name}: turned "
+                f"{'on' if new_val == 'on' else 'off'}"
+            )
+
+        if domain == "alarm_control_panel":
+            return (
+                f"[Home Assistant] {friendly_name}: alarm state changed from "
+                f"'{old_val}' to '{new_val}'"
+            )
+
+        # Generic fallback
+        return (
+            f"[Home Assistant] {friendly_name} ({entity_id}): "
+            f"changed from '{old_val}' to '{new_val}'"
+        )
+
+    # ------------------------------------------------------------------
+    # Outbound messaging
+    # ------------------------------------------------------------------
+
+    async def send(
+        self,
+        chat_id: str,
+        content: str,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        """Send a notification via HA REST API (persistent_notification.create).
+
+        Uses the REST API instead of WebSocket to avoid a race condition
+        with the event listener loop that reads from the same WS connection.
+        """
+        url = f"{self._hass_url}/api/services/persistent_notification/create"
+        headers = {
+            "Authorization": f"Bearer {self._hass_token}",
+            "Content-Type": "application/json",
+        }
+        payload = {
+            "title": "Hermes Agent",
+            "message": content[:self.MAX_MESSAGE_LENGTH],
+        }
+
+        try:
+            if self._rest_session:
+                async with self._rest_session.post(
+                    url,
+                    headers=headers,
+                    json=payload,
+                    timeout=aiohttp.ClientTimeout(total=10),
+                ) as resp:
+                    if resp.status < 300:
+                        return SendResult(success=True, message_id=uuid.uuid4().hex[:12])
+                    else:
+                        body = await resp.text()
+                        return SendResult(success=False, error=f"HTTP {resp.status}: {body}")
+            else:
+                async with aiohttp.ClientSession() as session:
+                    async with session.post(
+                        url,
+                        headers=headers,
+                        json=payload,
+                        timeout=aiohttp.ClientTimeout(total=10),
+                    ) as resp:
+                        if resp.status < 300:
+                            return SendResult(success=True, message_id=uuid.uuid4().hex[:12])
+                        else:
+                            body = await resp.text()
+                            return SendResult(success=False, error=f"HTTP {resp.status}: {body}")
+
+        except asyncio.TimeoutError:
+            return SendResult(success=False, error="Timeout sending notification to HA")
+        except Exception as e:
+            return SendResult(success=False, error=str(e))
+
+    async def send_typing(self, chat_id: str, metadata=None) -> None:
+        """No typing indicator for Home Assistant."""
+
+    async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
+        """Return basic info about the HA event channel."""
+        return {
+            "name": "Home Assistant Events",
+            "type": "channel",
+            "url": self._hass_url,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Standalone (out-of-process) sender — used by cron deliver=homeassistant
+# ---------------------------------------------------------------------------
+
+
+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]:
+    """Send a notification via the HA ``notify.notify`` service without a
+    live gateway adapter.
+
+    Used by ``tools/send_message_tool._send_via_adapter`` when the gateway
+    runner is not in this process (typical for cron jobs running
+    out-of-process).  The HTTP path is the same one the legacy
+    ``_send_homeassistant`` helper used in ``tools/send_message_tool.py``
+    before this migration.
+
+    Reads ``HASS_TOKEN`` from ``pconfig.token`` (set by the gateway config
+    loader from env) and falls back to the ``HASS_TOKEN`` env var.  Server
+    URL comes from ``pconfig.extra["url"]`` (seeded by the env loader in
+    ``gateway/config.py``) or the ``HASS_URL`` env var.
+
+    ``thread_id``, ``media_files`` and ``force_document`` are accepted for
+    signature parity with other standalone senders.  HA notifications have
+    no native threading or attachment model — these arguments are ignored.
+    """
+    if not AIOHTTP_AVAILABLE:
+        return {"error": "aiohttp not installed. Run: pip install aiohttp"}
+
+    extra = getattr(pconfig, "extra", {}) or {}
+    hass_url = (extra.get("url") or os.getenv("HASS_URL", "")).rstrip("/")
+    token = (getattr(pconfig, "token", None) or os.getenv("HASS_TOKEN", "")).strip()
+    if not hass_url or not token:
+        return {
+            "error": (
+                "Home Assistant standalone send: HASS_URL and HASS_TOKEN "
+                "must both be set"
+            )
+        }
+
+    url = f"{hass_url}/api/services/notify/notify"
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Content-Type": "application/json",
+    }
+    payload = {"message": message, "target": chat_id}
+
+    try:
+        async with aiohttp.ClientSession(
+            timeout=aiohttp.ClientTimeout(total=30)
+        ) as session:
+            async with session.post(url, headers=headers, json=payload) as resp:
+                if resp.status not in {200, 201}:
+                    body = await resp.text()
+                    return {
+                        "error": (
+                            f"Home Assistant API error ({resp.status}): {body}"
+                        )
+                    }
+        return {
+            "success": True,
+            "platform": "homeassistant",
+            "chat_id": chat_id,
+        }
+    except asyncio.TimeoutError:
+        return {"error": "Timeout sending notification to Home Assistant"}
+    except Exception as e:
+        return {"error": f"Home Assistant send failed: {e}"}
+
+
+# ---------------------------------------------------------------------------
+# is_connected probe
+# ---------------------------------------------------------------------------
+
+
+def _is_connected(config) -> bool:
+    """Home Assistant is considered connected when ``HASS_TOKEN`` is set.
+
+    Looks up via ``hermes_cli.gateway.get_env_value`` at call time (not via
+    the plugin's own bound import) so tests that patch
+    ``gateway_mod.get_env_value`` can suppress ambient ``HASS_TOKEN`` env
+    vars.  Matches what the legacy connected-platforms check did before
+    this migration.
+    """
+    import hermes_cli.gateway as gateway_mod
+    return bool((gateway_mod.get_env_value("HASS_TOKEN") or "").strip())
+
+
+# ---------------------------------------------------------------------------
+# Plugin registration entry point
+# ---------------------------------------------------------------------------
+
+
+def _build_adapter(config):
+    """Factory wrapper that constructs HomeAssistantAdapter from a PlatformConfig."""
+    return HomeAssistantAdapter(config)
+
+
+def register(ctx) -> None:
+    """Plugin entry point — called by the Hermes plugin system."""
+    ctx.register_platform(
+        name="homeassistant",
+        label="Home Assistant",
+        adapter_factory=_build_adapter,
+        check_fn=check_ha_requirements,
+        is_connected=_is_connected,
+        required_env=["HASS_TOKEN"],
+        install_hint="pip install aiohttp",
+        # Out-of-process cron delivery via the HA ``notify.notify`` service.
+        # Without this hook, ``deliver=homeassistant`` cron jobs would fail
+        # with "No live adapter" when cron runs separately from the gateway.
+        # Mirrors the Discord / Teams / Mattermost pattern.
+        standalone_sender_fn=_standalone_send,
+        # HA notification message cap — matches MAX_MESSAGE_LENGTH on the
+        # adapter class above.
+        max_message_length=HomeAssistantAdapter.MAX_MESSAGE_LENGTH,
+        # Display
+        emoji="🏠",
+        allow_update_command=True,
+    )

plugins/platforms/homeassistant/plugin.yaml

@@ -0,0 +1,22 @@
+name: homeassistant-platform
+label: Home Assistant
+kind: platform
+version: 1.0.0
+description: >
+  Home Assistant gateway adapter for Hermes Agent.
+  Subscribes to HA's WebSocket event bus and forwards state-change events
+  (with per-entity cooldowns and domain/entity filtering) to the agent.
+  Outbound messages are delivered as HA persistent notifications via the
+  REST API. Out-of-process cron delivery via the ``notify.notify``
+  service is also supported.
+author: NousResearch
+requires_env:
+  - name: HASS_TOKEN
+    description: "Home Assistant Long-Lived Access Token"
+    prompt: "Home Assistant Long-Lived Access Token"
+    password: true
+optional_env:
+  - name: HASS_URL
+    description: "Home Assistant base URL (default: http://homeassistant.local:8123)"
+    prompt: "Home Assistant URL"
+    password: false

plugins/platforms/irc/__init__.py

@@ -0,0 +1,3 @@
+from .adapter import register
+
+__all__ = ["register"]

plugins/platforms/irc/adapter.py

@@ -0,0 +1,971 @@
+"""
+IRC Platform Adapter for Hermes Agent.
+
+A plugin-based gateway adapter that connects to an IRC server and relays
+messages to/from the Hermes agent.  Zero external dependencies — uses
+Python's stdlib asyncio for the IRC protocol.
+
+Configuration in config.yaml::
+
+    gateway:
+      platforms:
+        irc:
+          enabled: true
+          extra:
+            server: irc.libera.chat
+            port: 6697
+            nickname: hermes-bot
+            channel: "#hermes"
+            use_tls: true
+            server_password: ""       # optional server password
+            nickserv_password: ""     # optional NickServ identification
+            allowed_users: []         # empty = allow all, or list of nicks
+            max_message_length: 450   # IRC line limit (safe default)
+
+Or via environment variables (overrides config.yaml):
+    IRC_SERVER, IRC_PORT, IRC_NICKNAME, IRC_CHANNEL, IRC_USE_TLS,
+    IRC_SERVER_PASSWORD, IRC_NICKSERV_PASSWORD
+"""
+
+import asyncio
+import logging
+import os
+import re
+import ssl
+import time
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Lazy import: BasePlatformAdapter and friends live in the main repo.
+# We import at function/class level to avoid import errors when the plugin
+# is discovered but the gateway hasn't been fully initialised yet.
+# ---------------------------------------------------------------------------
+
+from gateway.platforms.base import (
+    BasePlatformAdapter,
+    SendResult,
+    MessageEvent,
+    MessageType,
+)
+from gateway.config import Platform
+
+
+# ---------------------------------------------------------------------------
+# IRC protocol helpers
+# ---------------------------------------------------------------------------
+
+def _parse_irc_message(raw: str) -> dict:
+    """Parse a raw IRC protocol line into components.
+
+    Returns dict with keys: prefix, command, params.
+    """
+    prefix = ""
+    trailing = ""
+
+    if raw.startswith(":"):
+        try:
+            prefix, raw = raw[1:].split(" ", 1)
+        except ValueError:
+            prefix = raw[1:]
+            raw = ""
+
+    if " :" in raw:
+        raw, trailing = raw.split(" :", 1)
+
+    parts = raw.split()
+    command = parts[0] if parts else ""
+    params = parts[1:] if len(parts) > 1 else []
+    if trailing:
+        params.append(trailing)
+
+    return {"prefix": prefix, "command": command, "params": params}
+
+
+def _extract_nick(prefix: str) -> str:
+    """Extract nickname from IRC prefix (nick!user@host)."""
+    return prefix.split("!")[0] if "!" in prefix else prefix
+
+
+# ---------------------------------------------------------------------------
+# IRC Adapter
+# ---------------------------------------------------------------------------
+
+class IRCAdapter(BasePlatformAdapter):
+    """Async IRC adapter implementing the BasePlatformAdapter interface.
+
+    This class is instantiated by the adapter_factory passed to
+    register_platform().
+    """
+
+    def __init__(self, config, **kwargs):
+        platform = Platform("irc")
+        super().__init__(config=config, platform=platform)
+
+        extra = getattr(config, "extra", {}) or {}
+
+        # Connection settings (env vars override config.yaml)
+        self.server = os.getenv("IRC_SERVER") or extra.get("server", "")
+        try:
+            self.port = int(os.getenv("IRC_PORT") or extra.get("port", 6697))
+        except (ValueError, TypeError):
+            self.port = 6697
+        self.nickname = os.getenv("IRC_NICKNAME") or extra.get("nickname", "hermes-bot")
+        self.channel = os.getenv("IRC_CHANNEL") or extra.get("channel", "")
+        self.use_tls = (
+            os.getenv("IRC_USE_TLS", "").lower() in {"1", "true", "yes"}
+            if os.getenv("IRC_USE_TLS")
+            else extra.get("use_tls", True)
+        )
+        self.server_password = os.getenv("IRC_SERVER_PASSWORD") or extra.get("server_password", "")
+        self.nickserv_password = os.getenv("IRC_NICKSERV_PASSWORD") or extra.get("nickserv_password", "")
+
+        # Auth
+        self.allowed_users: list = extra.get("allowed_users", [])
+        # IRC nicks are case-insensitive — normalise for lookups
+        self._allowed_users_lower: set = {u.lower() for u in self.allowed_users if isinstance(u, str)}
+
+        # IRC limits
+        max_msg = extra.get("max_message_length")
+        if max_msg is None:
+            try:
+                from gateway.platform_registry import platform_registry
+                entry = platform_registry.get("irc")
+                if entry and entry.max_message_length:
+                    max_msg = entry.max_message_length
+            except Exception:
+                pass
+        self.max_message_length = int(max_msg or 450)
+
+        # Runtime state
+        self._reader: Optional[asyncio.StreamReader] = None
+        self._writer: Optional[asyncio.StreamWriter] = None
+        self._recv_task: Optional[asyncio.Task] = None
+        self._current_nick = self.nickname
+        self._registered = False  # IRC registration complete
+        self._registration_event = asyncio.Event()
+
+    @property
+    def name(self) -> str:
+        return "IRC"
+
+    # ── Connection lifecycle ──────────────────────────────────────────────
+
+    async def connect(self) -> bool:
+        """Connect to the IRC server, register, and join the channel."""
+        if not self.server or not self.channel:
+            logger.error("IRC: server and channel must be configured")
+            self._set_fatal_error(
+                "config_missing",
+                "IRC_SERVER and IRC_CHANNEL must be set",
+                retryable=False,
+            )
+            return False
+
+        # Prevent two profiles from using the same IRC identity
+        try:
+            from gateway.status import acquire_scoped_lock, release_scoped_lock
+            lock_key = f"{self.server}:{self.nickname}"
+            if not acquire_scoped_lock("irc", lock_key):
+                logger.error("IRC: %s@%s already in use by another profile", self.nickname, self.server)
+                self._set_fatal_error("lock_conflict", "IRC identity in use by another profile", retryable=False)
+                return False
+            self._lock_key = lock_key
+        except ImportError:
+            self._lock_key = None  # status module not available (e.g. tests)
+
+        try:
+            ssl_ctx = None
+            if self.use_tls:
+                ssl_ctx = ssl.create_default_context()
+
+            self._reader, self._writer = await asyncio.wait_for(
+                asyncio.open_connection(self.server, self.port, ssl=ssl_ctx),
+                timeout=30.0,
+            )
+        except Exception as e:
+            logger.error("IRC: failed to connect to %s:%s — %s", self.server, self.port, e)
+            self._set_fatal_error("connect_failed", str(e), retryable=True)
+            return False
+
+        # IRC registration sequence
+        if self.server_password:
+            await self._send_raw(f"PASS {self.server_password}")
+        await self._send_raw(f"NICK {self.nickname}")
+        await self._send_raw(f"USER {self.nickname} 0 * :Hermes Agent")
+
+        # Start receive loop
+        self._recv_task = asyncio.create_task(self._receive_loop())
+
+        # Wait for registration (001 RPL_WELCOME) with timeout
+        try:
+            await asyncio.wait_for(self._registration_event.wait(), timeout=30.0)
+        except asyncio.TimeoutError:
+            logger.error("IRC: registration timed out")
+            await self.disconnect()
+            self._set_fatal_error("registration_timeout", "IRC server did not send RPL_WELCOME", retryable=True)
+            return False
+
+        # NickServ identification
+        if self.nickserv_password:
+            await self._send_raw(f"PRIVMSG NickServ :IDENTIFY {self.nickserv_password}")
+            await asyncio.sleep(2)  # Give NickServ time to process
+
+        # Join channel
+        await self._send_raw(f"JOIN {self.channel}")
+
+        self._mark_connected()
+        logger.info("IRC: connected to %s:%s as %s, joined %s", self.server, self.port, self._current_nick, self.channel)
+        return True
+
+    async def disconnect(self) -> None:
+        """Quit and close the connection."""
+        # Release the scoped lock so another profile can use this identity
+        if getattr(self, "_lock_key", None):
+            try:
+                from gateway.status import release_scoped_lock
+                release_scoped_lock("irc", self._lock_key)
+            except Exception:
+                pass
+        self._mark_disconnected()
+        if self._writer and not self._writer.is_closing():
+            try:
+                await self._send_raw("QUIT :Hermes Agent shutting down")
+                await asyncio.sleep(0.5)
+            except Exception:
+                pass
+            try:
+                self._writer.close()
+                await self._writer.wait_closed()
+            except Exception:
+                pass
+
+        if self._recv_task and not self._recv_task.done():
+            self._recv_task.cancel()
+            try:
+                await self._recv_task
+            except asyncio.CancelledError:
+                pass
+
+        self._reader = None
+        self._writer = None
+        self._registered = False
+        self._registration_event.clear()
+
+    # ── Sending ───────────────────────────────────────────────────────────
+
+    async def send(
+        self,
+        chat_id: str,
+        content: str,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ):
+        if not self._writer or self._writer.is_closing():
+            return SendResult(success=False, error="Not connected")
+
+        target = chat_id  # channel name or nick for DMs
+        lines = self._split_message(content, target)
+
+        for line in lines:
+            try:
+                await self._send_raw(f"PRIVMSG {target} :{line}")
+                # Basic rate limiting to avoid excess flood
+                await asyncio.sleep(0.3)
+            except Exception as e:
+                return SendResult(success=False, error=str(e))
+
+        return SendResult(success=True, message_id=str(int(time.time() * 1000)))
+
+    async def send_typing(self, chat_id: str, metadata=None) -> None:
+        """IRC has no typing indicator — no-op."""
+        pass
+
+    async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
+        is_channel = chat_id.startswith("#") or chat_id.startswith("&")
+        return {
+            "name": chat_id,
+            "type": "group" if is_channel else "dm",
+        }
+
+    # ── Message splitting ─────────────────────────────────────────────────
+
+    def _split_message(self, content: str, target: str) -> List[str]:
+        """Split a long message into IRC-safe chunks.
+
+        IRC has a ~512 byte line limit.  After accounting for protocol
+        overhead (``PRIVMSG <target> :``), we split content into chunks.
+        """
+        # Strip markdown formatting that doesn't render in IRC
+        content = self._strip_markdown(content)
+
+        overhead = len(f"PRIVMSG {target} :".encode("utf-8")) + 2  # +2 for \r\n
+        max_bytes = 510 - overhead
+        user_limit = self.max_message_length
+
+        lines: List[str] = []
+        for paragraph in content.split("\n"):
+            if not paragraph.strip():
+                continue
+            while True:
+                para_bytes = paragraph.encode("utf-8")
+                limit = min(user_limit, max_bytes)
+                if len(para_bytes) <= limit:
+                    if paragraph.strip():
+                        lines.append(paragraph)
+                    break
+                # Binary search for a safe character boundary <= limit
+                low, high = 1, len(paragraph)
+                best = 0
+                while low <= high:
+                    mid = (low + high) // 2
+                    if len(paragraph[:mid].encode("utf-8")) <= limit:
+                        best = mid
+                        low = mid + 1
+                    else:
+                        high = mid - 1
+                split_at = best
+                # Prefer a space boundary
+                space = paragraph.rfind(" ", 0, split_at)
+                if space > split_at // 3:
+                    split_at = space
+                lines.append(paragraph[:split_at].rstrip())
+                paragraph = paragraph[split_at:].lstrip()
+
+        return lines if lines else [""]
+
+    @staticmethod
+    def _strip_markdown(text: str) -> str:
+        """Convert basic markdown to plain text for IRC."""
+        # Bold: **text** or __text__ → text
+        text = re.sub(r"\*\*(.+?)\*\*", r"\1", text)
+        text = re.sub(r"__(.+?)__", r"\1", text)
+        # Italic: *text* or _text_ → text
+        text = re.sub(r"\*(.+?)\*", r"\1", text)
+        text = re.sub(r"(?<!\w)_(.+?)_(?!\w)", r"\1", text)
+        # Inline code: `text` → text
+        text = re.sub(r"`(.+?)`", r"\1", text)
+        # Code blocks: ```...``` → content
+        text = re.sub(r"```\w*\n?", "", text)
+        # Images: ![alt](url) → url  (must come BEFORE links)
+        text = re.sub(r"!\[([^\]]*)\]\(([^)]+)\)", r"\2", text)
+        # Links: [text](url) → text (url)
+        text = re.sub(r"\[([^\]]+)\]\(([^)]+)\)", r"\1 (\2)", text)
+        return text
+
+    # ── Raw IRC I/O ──────────────────────────────────────────────────────
+
+    async def _send_raw(self, line: str) -> None:
+        """Send a raw IRC protocol line."""
+        if not self._writer or self._writer.is_closing():
+            return
+        encoded = (line + "\r\n").encode("utf-8")
+        self._writer.write(encoded)
+        await self._writer.drain()
+
+    async def _receive_loop(self) -> None:
+        """Main receive loop — reads lines and dispatches them."""
+        buffer = b""
+        try:
+            while self._reader and not self._reader.at_eof():
+                data = await self._reader.read(4096)
+                if not data:
+                    break
+                buffer += data
+                while b"\r\n" in buffer:
+                    line, buffer = buffer.split(b"\r\n", 1)
+                    try:
+                        decoded = line.decode("utf-8", errors="replace")
+                        await self._handle_line(decoded)
+                    except Exception as e:
+                        logger.warning("IRC: error handling line: %s", e)
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:
+            logger.error("IRC: receive loop error: %s", e)
+        finally:
+            if self.is_connected:
+                logger.warning("IRC: connection lost, marking disconnected")
+                self._set_fatal_error("connection_lost", "IRC connection closed unexpectedly", retryable=True)
+                await self._notify_fatal_error()
+
+    async def _handle_line(self, raw: str) -> None:
+        """Dispatch a single IRC protocol line."""
+        msg = _parse_irc_message(raw)
+        command = msg["command"]
+        params = msg["params"]
+
+        # PING/PONG keepalive
+        if command == "PING":
+            payload = params[0] if params else ""
+            await self._send_raw(f"PONG :{payload}")
+            return
+
+        # RPL_WELCOME (001) — registration complete
+        if command == "001":
+            self._registered = True
+            self._registration_event.set()
+            if params:
+                # Server may confirm our nick in the first param
+                self._current_nick = params[0]
+            return
+
+        # ERR_NICKNAMEINUSE (433) — nick collision during registration
+        if command == "433":
+            # Retry with incrementing suffix: hermes_, hermes_1, hermes_2...
+            base = self.nickname.rstrip("_0123456789")
+            suffix_match = re.search(r"_(\d+)$", self._current_nick)
+            if suffix_match:
+                next_num = int(suffix_match.group(1)) + 1
+                self._current_nick = f"{base}_{next_num}"
+            elif self._current_nick == self.nickname:
+                self._current_nick = self.nickname + "_"
+            else:
+                self._current_nick = self.nickname + "_1"
+            await self._send_raw(f"NICK {self._current_nick}")
+            return
+
+        # PRIVMSG — incoming message (channel or DM)
+        if command == "PRIVMSG" and len(params) >= 2:
+            sender_nick = _extract_nick(msg["prefix"])
+            target = params[0]
+            text = params[1]
+
+            # Ignore our own messages
+            if sender_nick.lower() == self._current_nick.lower():
+                return
+
+            # CTCP ACTION (/me) — convert to text
+            if text.startswith("\x01ACTION ") and text.endswith("\x01"):
+                text = f"* {sender_nick} {text[8:-1]}"
+
+            # Ignore other CTCP
+            if text.startswith("\x01"):
+                return
+
+            # Determine if this is a channel message or DM
+            is_channel = target.startswith("#") or target.startswith("&")
+            chat_id = target if is_channel else sender_nick
+            chat_type = "group" if is_channel else "dm"
+
+            # In channels, only respond if addressed (nick: or nick,)
+            if is_channel:
+                addressed = False
+                for prefix in (f"{self._current_nick}:", f"{self._current_nick},",
+                               f"{self._current_nick} "):
+                    if text.lower().startswith(prefix.lower()):
+                        text = text[len(prefix):].strip()
+                        addressed = True
+                        break
+                if not addressed:
+                    return  # Ignore unaddressed channel messages
+
+            # Auth check (case-insensitive)
+            if self._allowed_users_lower and sender_nick.lower() not in self._allowed_users_lower:
+                logger.debug("IRC: ignoring message from unauthorized user %s", sender_nick)
+                return
+
+            await self._dispatch_message(
+                text=text,
+                chat_id=chat_id,
+                chat_type=chat_type,
+                user_id=sender_nick,
+                user_name=sender_nick,
+            )
+
+        # NICK — track our own nick changes
+        if command == "NICK" and _extract_nick(msg["prefix"]).lower() == self._current_nick.lower():
+            if params:
+                self._current_nick = params[0]
+
+    async def _dispatch_message(
+        self,
+        text: str,
+        chat_id: str,
+        chat_type: str,
+        user_id: str,
+        user_name: str,
+    ) -> None:
+        """Build a MessageEvent and hand it to the base class handler."""
+        if not self._message_handler:
+            return
+
+        source = self.build_source(
+            chat_id=chat_id,
+            chat_name=chat_id,
+            chat_type=chat_type,
+            user_id=user_id,
+            user_name=user_name,
+        )
+
+        event = MessageEvent(
+            text=text,
+            message_type=MessageType.TEXT,
+            source=source,
+            message_id=str(int(time.time() * 1000)),
+            timestamp=__import__("datetime").datetime.now(),
+        )
+
+        await self.handle_message(event)
+
+
+# ---------------------------------------------------------------------------
+# Plugin registration
+# ---------------------------------------------------------------------------
+
+def check_requirements() -> bool:
+    """Check if IRC is configured.
+
+    Only requires the server and channel — no external pip packages needed.
+    """
+    server = os.getenv("IRC_SERVER", "")
+    channel = os.getenv("IRC_CHANNEL", "")
+    # Also accept config.yaml-only configuration (no env vars).
+    # The gateway passes PlatformConfig; we just check env for the
+    # hermes setup / requirements check path.
+    return bool(server and channel)
+
+
+def validate_config(config) -> bool:
+    """Validate that the platform config has enough info to connect."""
+    extra = getattr(config, "extra", {}) or {}
+    server = os.getenv("IRC_SERVER") or extra.get("server", "")
+    channel = os.getenv("IRC_CHANNEL") or extra.get("channel", "")
+    return bool(server and channel)
+
+
+def interactive_setup() -> None:
+    """Interactive `hermes gateway setup` flow for the IRC platform.
+
+    Lazy-imports ``hermes_cli.setup`` helpers so the plugin stays importable
+    in non-CLI contexts (gateway runtime, tests).
+    """
+    from hermes_cli.setup import (
+        prompt,
+        prompt_yes_no,
+        save_env_value,
+        get_env_value,
+        print_header,
+        print_info,
+        print_warning,
+        print_success,
+    )
+
+    print_header("IRC")
+    existing_server = get_env_value("IRC_SERVER")
+    if existing_server:
+        print_info(f"IRC: already configured (server: {existing_server})")
+        if not prompt_yes_no("Reconfigure IRC?", False):
+            return
+
+    print_info("Connect Hermes to an IRC network. Uses Python stdlib — no extra packages needed.")
+    print_info("   Works with Libera.Chat, OFTC, your own ZNC/InspIRCd, etc.")
+    print()
+
+    server = prompt("IRC server hostname (e.g. irc.libera.chat)", default=existing_server or "")
+    if not server:
+        print_warning("Server is required — skipping IRC setup")
+        return
+    save_env_value("IRC_SERVER", server.strip())
+
+    use_tls = prompt_yes_no("Use TLS (recommended)?", True)
+    save_env_value("IRC_USE_TLS", "true" if use_tls else "false")
+
+    default_port = "6697" if use_tls else "6667"
+    port = prompt(f"Port (default {default_port})", default=get_env_value("IRC_PORT") or "")
+    if port:
+        try:
+            save_env_value("IRC_PORT", str(int(port)))
+        except ValueError:
+            print_warning(f"Invalid port — using default {default_port}")
+    elif get_env_value("IRC_PORT"):
+        # User cleared the prompt; drop the override so the default applies.
+        save_env_value("IRC_PORT", "")
+
+    nickname = prompt(
+        "Bot nickname (e.g. hermes-bot)",
+        default=get_env_value("IRC_NICKNAME") or "",
+    )
+    if not nickname:
+        print_warning("Nickname is required — skipping IRC setup")
+        return
+    save_env_value("IRC_NICKNAME", nickname.strip())
+
+    channel = prompt(
+        "Channel to join (e.g. #hermes — comma-separate for multiple)",
+        default=get_env_value("IRC_CHANNEL") or "",
+    )
+    if not channel:
+        print_warning("Channel is required — skipping IRC setup")
+        return
+    save_env_value("IRC_CHANNEL", channel.strip())
+
+    print()
+    print_info("🔑 Optional authentication")
+    print_info("   Leave blank to skip.")
+    if prompt_yes_no("Configure a server password (PASS command)?", False):
+        server_password = prompt("Server password", password=True)
+        if server_password:
+            save_env_value("IRC_SERVER_PASSWORD", server_password)
+
+    if prompt_yes_no("Identify with NickServ on connect?", False):
+        nickserv = prompt("NickServ password", password=True)
+        if nickserv:
+            save_env_value("IRC_NICKSERV_PASSWORD", nickserv)
+
+    print()
+    print_info("🔒 Access control: restrict who can message the bot")
+    print_info("   IRC nicks are not authenticated — anyone can claim any nick.")
+    print_info("   For public channels, pair with NickServ-only mode on your network")
+    print_info("   if you want stronger identity guarantees.")
+    allow_all = prompt_yes_no("Allow all users in the channel to talk to the bot?", False)
+    if allow_all:
+        save_env_value("IRC_ALLOW_ALL_USERS", "true")
+        save_env_value("IRC_ALLOWED_USERS", "")
+        print_warning("⚠️  Open access — any nick in the channel can command the bot.")
+    else:
+        save_env_value("IRC_ALLOW_ALL_USERS", "false")
+        allowed = prompt(
+            "Allowed nicks (comma-separated, leave empty to deny everyone)",
+            default=get_env_value("IRC_ALLOWED_USERS") or "",
+        )
+        if allowed:
+            save_env_value("IRC_ALLOWED_USERS", allowed.replace(" ", ""))
+            print_success("Allowlist configured")
+        else:
+            save_env_value("IRC_ALLOWED_USERS", "")
+            print_info("No nicks allowed — the bot will ignore all messages until you add nicks.")
+
+    print()
+    print_success("IRC configuration saved to ~/.hermes/.env")
+    print_info("Restart the gateway for changes to take effect: hermes gateway restart")
+
+
+def is_connected(config) -> bool:
+    """Check whether IRC is configured (env or config.yaml)."""
+    extra = getattr(config, "extra", {}) or {}
+    server = os.getenv("IRC_SERVER") or extra.get("server", "")
+    channel = os.getenv("IRC_CHANNEL") or extra.get("channel", "")
+    return bool(server and channel)
+
+
+def _env_enablement() -> dict | None:
+    """Seed ``PlatformConfig.extra`` from env vars during gateway config load.
+
+    Called by the platform registry's env-enablement hook (landed in the
+    generic-plugin-interface migration) BEFORE adapter construction, so
+    ``gateway status`` and ``get_connected_platforms()`` reflect env-only
+    configuration without instantiating the IRC client.  Returns ``None``
+    when IRC isn't minimally configured; the caller skips auto-enabling.
+
+    The special ``home_channel`` key in the returned dict is handled by
+    the core hook — it becomes a proper ``HomeChannel`` dataclass on the
+    ``PlatformConfig`` rather than being merged into ``extra``.
+    """
+    server = os.getenv("IRC_SERVER", "").strip()
+    channel = os.getenv("IRC_CHANNEL", "").strip()
+    if not (server and channel):
+        return None
+    seed: dict = {
+        "server": server,
+        "channel": channel,
+    }
+    port = os.getenv("IRC_PORT", "").strip()
+    if port:
+        try:
+            seed["port"] = int(port)
+        except ValueError:
+            pass
+    nickname = os.getenv("IRC_NICKNAME", "").strip()
+    if nickname:
+        seed["nickname"] = nickname
+    use_tls = os.getenv("IRC_USE_TLS", "").strip().lower()
+    if use_tls:
+        seed["use_tls"] = use_tls in {"1", "true", "yes"}
+    # Passwords live in PlatformConfig.extra as well for back-compat with
+    # existing config.yaml users; env-reads at construct time still win.
+    if os.getenv("IRC_SERVER_PASSWORD"):
+        seed["server_password"] = os.getenv("IRC_SERVER_PASSWORD")
+    if os.getenv("IRC_NICKSERV_PASSWORD"):
+        seed["nickserv_password"] = os.getenv("IRC_NICKSERV_PASSWORD")
+    # Optional home-channel (usually the same as IRC_CHANNEL, but can be a
+    # dedicated reports channel).  Defaults to IRC_CHANNEL so cron jobs
+    # with ``deliver=irc`` have a sensible target without extra config.
+    home = os.getenv("IRC_HOME_CHANNEL") or channel
+    if home:
+        seed["home_channel"] = {
+            "chat_id": home,
+            "name": os.getenv("IRC_HOME_CHANNEL_NAME", home),
+        }
+    return seed
+
+
+def _strip_irc_control_chars(text: str) -> str:
+    """Strip IRC line terminators and the NUL byte from ``text``.
+
+    IRC commands are CRLF-delimited; a bare ``\\r`` or ``\\n`` in user
+    content lets an attacker inject arbitrary IRC commands (CTCP, JOIN,
+    KICK).  ``\\x00`` is a protocol-illegal byte.  Everything else is
+    valid in PRIVMSG payloads.
+    """
+    return text.replace("\r", " ").replace("\n", " ").replace("\x00", "")
+
+
+def _is_irc_channel(target: str) -> bool:
+    return bool(target) and target[0] in "#&+!"
+
+
+async def _standalone_send(
+    pconfig,
+    chat_id: str,
+    message: str,
+    *,
+    thread_id: Optional[str] = None,
+    media_files: Optional[List[str]] = None,
+    force_document: bool = False,
+) -> Dict[str, Any]:
+    """Open an ephemeral IRC connection, send a PRIVMSG, and quit.
+
+    Used by ``tools/send_message_tool._send_via_adapter`` when the gateway
+    runner is not in this process (e.g. ``hermes cron`` running as a
+    separate process from ``hermes gateway``).  Without this hook,
+    ``deliver=irc`` cron jobs fail with ``No live adapter for platform``.
+
+    The standalone client uses a distinct nick suffix (``-cron``) so it
+    does not collide with the long-running gateway adapter that may already
+    be holding the configured nickname on the same network.  When the
+    target is a channel, the client JOINs it before sending PRIVMSG so
+    networks with the default ``+n`` (no external messages) channel mode
+    accept the delivery.
+
+    ``thread_id`` and ``media_files`` are accepted for signature parity but
+    are not meaningful on IRC: IRC has no native thread or attachment
+    primitive.
+    """
+    extra = getattr(pconfig, "extra", {}) or {}
+    server = os.getenv("IRC_SERVER") or extra.get("server", "")
+    channel = os.getenv("IRC_CHANNEL") or extra.get("channel", "")
+    if not server or not channel:
+        return {"error": "IRC standalone send: IRC_SERVER and IRC_CHANNEL must be configured"}
+
+    port_value = os.getenv("IRC_PORT") or extra.get("port", 6697)
+    try:
+        port = int(port_value)
+    except (TypeError, ValueError):
+        return {"error": f"IRC standalone send: invalid port {port_value!r}"}
+
+    nickname = os.getenv("IRC_NICKNAME") or extra.get("nickname", "hermes-bot")
+    use_tls_env = os.getenv("IRC_USE_TLS")
+    if use_tls_env is not None:
+        use_tls = use_tls_env.lower() in {"1", "true", "yes"}
+    else:
+        use_tls = bool(extra.get("use_tls", True))
+
+    server_password = os.getenv("IRC_SERVER_PASSWORD") or extra.get("server_password", "")
+    nickserv_password = os.getenv("IRC_NICKSERV_PASSWORD") or extra.get("nickserv_password", "")
+
+    # Reject control characters in chat_id to block IRC command injection.
+    raw_target = chat_id or channel
+    if any(ch in raw_target for ch in ("\r", "\n", "\x00", " ")):
+        return {"error": "IRC standalone send: chat_id contains illegal IRC characters"}
+    target = raw_target
+
+    # Distinct nick prevents NICK collision with a live gateway adapter
+    # that may already be holding the configured nickname.  Cap to 24 chars
+    # so subsequent collision retries do not overflow the 30-char NICKLEN
+    # most networks enforce.
+    nick_base = nickname.rstrip("_0123456789-")[:24] or "hermes-bot"
+    standalone_nick = f"{nick_base}-cron"[:30]
+    plain = IRCAdapter._strip_markdown(message)
+
+    ssl_ctx = ssl.create_default_context() if use_tls else None
+    try:
+        reader, writer = await asyncio.wait_for(
+            asyncio.open_connection(server, port, ssl=ssl_ctx),
+            timeout=15.0,
+        )
+    except asyncio.CancelledError:
+        raise
+    except Exception as e:
+        return {"error": f"IRC standalone connect failed: {e}"}
+
+    async def _raw(line: str) -> None:
+        writer.write((line + "\r\n").encode("utf-8"))
+        await writer.drain()
+
+    nick_attempts = 0
+    max_nick_attempts = 5
+    try:
+        if server_password:
+            await _raw(f"PASS {_strip_irc_control_chars(server_password)}")
+        await _raw(f"NICK {standalone_nick}")
+        await _raw(f"USER {standalone_nick} 0 * :Hermes Agent (cron)")
+
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + 15.0
+        registered = False
+        while not registered:
+            remaining = deadline - loop.time()
+            if remaining <= 0:
+                return {"error": "IRC standalone send: registration timeout (no RPL_WELCOME)"}
+            try:
+                raw_line = await asyncio.wait_for(reader.readuntil(b"\r\n"), timeout=remaining)
+            except asyncio.TimeoutError:
+                return {"error": "IRC standalone send: registration timeout (no RPL_WELCOME)"}
+            except asyncio.IncompleteReadError:
+                return {"error": "IRC standalone send: server closed connection during registration"}
+            decoded = raw_line.decode("utf-8", errors="replace").rstrip("\r\n")
+            msg = _parse_irc_message(decoded)
+            cmd = msg["command"]
+            if cmd == "PING":
+                payload = msg["params"][0] if msg["params"] else ""
+                await _raw(f"PONG :{payload}")
+            elif cmd == "001":
+                registered = True
+            elif cmd in {"432", "433"}:
+                nick_attempts += 1
+                if nick_attempts > max_nick_attempts:
+                    return {"error": "IRC standalone send: too many nick collisions"}
+                # Build the next nick from the stable base, not the
+                # mutated value, so the suffix stays bounded.
+                standalone_nick = f"{nick_base}-cron-{nick_attempts}"[:30]
+                await _raw(f"NICK {standalone_nick}")
+            elif cmd in {"464", "465"}:
+                return {"error": f"IRC standalone send: server rejected client ({cmd})"}
+
+        if nickserv_password:
+            await _raw(f"PRIVMSG NickServ :IDENTIFY {_strip_irc_control_chars(nickserv_password)}")
+            await asyncio.sleep(2)
+
+        # JOIN before PRIVMSG.  IRC channels with the default ``+n`` mode
+        # (no external messages: Libera, OFTC, EFnet, IRCNet, undernet)
+        # silently drop PRIVMSG from non-members.  Do not JOIN bare nicks
+        # (DM target) or server queries.
+        if _is_irc_channel(target):
+            await _raw(f"JOIN {target}")
+            join_deadline = loop.time() + 5.0
+            joined = False
+            while not joined:
+                remaining = join_deadline - loop.time()
+                if remaining <= 0:
+                    # Timed out waiting for a JOIN ack: proceed anyway, the
+                    # server may still deliver the PRIVMSG depending on mode.
+                    break
+                try:
+                    raw_line = await asyncio.wait_for(reader.readuntil(b"\r\n"), timeout=remaining)
+                except (asyncio.TimeoutError, asyncio.IncompleteReadError):
+                    break
+                decoded = raw_line.decode("utf-8", errors="replace").rstrip("\r\n")
+                jmsg = _parse_irc_message(decoded)
+                jcmd = jmsg["command"]
+                if jcmd == "PING":
+                    payload = jmsg["params"][0] if jmsg["params"] else ""
+                    await _raw(f"PONG :{payload}")
+                elif jcmd in {"366", "JOIN"}:
+                    joined = True
+                elif jcmd in {"403", "405", "471", "473", "474", "475"}:
+                    return {"error": f"IRC standalone send: JOIN {target} rejected ({jcmd})"}
+
+        # Bytes-aware per-line splitting so multi-line plain text never
+        # exceeds the IRC 510-byte protocol limit.  Reuses the same
+        # algorithm as IRCAdapter._split_message, with control-character
+        # stripping per line to block CRLF injection from message content.
+        overhead = len(f"PRIVMSG {target} :".encode("utf-8")) + 2
+        max_bytes = 510 - overhead
+        sent_any = False
+        for paragraph in plain.split("\n"):
+            paragraph = _strip_irc_control_chars(paragraph).rstrip()
+            if not paragraph:
+                continue
+            while paragraph:
+                encoded = paragraph.encode("utf-8")
+                if len(encoded) <= max_bytes:
+                    await _raw(f"PRIVMSG {target} :{paragraph}")
+                    await asyncio.sleep(0.3)
+                    sent_any = True
+                    break
+                # Binary search for largest prefix that fits within max_bytes
+                low, high, best = 1, len(paragraph), 0
+                while low <= high:
+                    mid = (low + high) // 2
+                    if len(paragraph[:mid].encode("utf-8")) <= max_bytes:
+                        best = mid
+                        low = mid + 1
+                    else:
+                        high = mid - 1
+                split_at = best
+                space = paragraph.rfind(" ", 0, split_at)
+                if space > split_at // 3:
+                    split_at = space
+                await _raw(f"PRIVMSG {target} :{paragraph[:split_at].rstrip()}")
+                await asyncio.sleep(0.3)
+                sent_any = True
+                paragraph = paragraph[split_at:].lstrip()
+
+        if not sent_any:
+            return {"error": "IRC standalone send: empty message after stripping"}
+
+        await _raw("QUIT :delivered")
+        try:
+            await asyncio.wait_for(reader.read(1024), timeout=2.0)
+        except asyncio.TimeoutError:
+            pass
+
+        return {"success": True, "message_id": str(int(time.time() * 1000))}
+    except asyncio.CancelledError:
+        raise
+    except Exception as e:
+        logger.debug("IRC standalone send raised", exc_info=True)
+        return {"error": f"IRC standalone send failed: {e}"}
+    finally:
+        try:
+            writer.close()
+            await asyncio.wait_for(writer.wait_closed(), timeout=5.0)
+        except (asyncio.TimeoutError, Exception):
+            pass
+
+
+def register(ctx):
+    """Plugin entry point: called by the Hermes plugin system."""
+    ctx.register_platform(
+        name="irc",
+        label="IRC",
+        adapter_factory=lambda cfg: IRCAdapter(cfg),
+        check_fn=check_requirements,
+        validate_config=validate_config,
+        is_connected=is_connected,
+        required_env=["IRC_SERVER", "IRC_CHANNEL", "IRC_NICKNAME"],
+        install_hint="No extra packages needed (stdlib only)",
+        setup_fn=interactive_setup,
+        # Env-driven auto-configuration: seeds PlatformConfig.extra with
+        # server/channel/port/tls + home_channel so env-only setups show
+        # up in gateway status without instantiating the adapter.
+        env_enablement_fn=_env_enablement,
+        # Cron home-channel delivery support.  IRC_HOME_CHANNEL defaults to
+        # IRC_CHANNEL (see _env_enablement), so cron jobs with
+        # deliver=irc route to the joined channel by default.
+        cron_deliver_env_var="IRC_HOME_CHANNEL",
+        # Out-of-process cron delivery.  Without this hook, deliver=irc
+        # cron jobs fail with "No live adapter" when cron runs separately
+        # from the gateway.
+        standalone_sender_fn=_standalone_send,
+        # Auth env vars for _is_user_authorized() integration
+        allowed_users_env="IRC_ALLOWED_USERS",
+        allow_all_env="IRC_ALLOW_ALL_USERS",
+        # IRC line limit after protocol overhead
+        max_message_length=450,
+        # Display
+        emoji="💬",
+        # IRC doesn't have phone numbers to redact
+        pii_safe=False,
+        allow_update_command=True,
+        # LLM guidance
+        platform_hint=(
+            "You are chatting via IRC. IRC does not support markdown formatting "
+            "— use plain text only. Messages are limited to ~450 characters per "
+            "line (long messages are automatically split). In channels, users "
+            "address you by prefixing your nick. Keep responses concise and "
+            "conversational."
+        ),
+    )

plugins/platforms/irc/plugin.yaml

@@ -0,0 +1,54 @@
+name: irc-platform
+label: IRC
+kind: platform
+version: 1.0.0
+description: >
+  IRC gateway adapter for Hermes Agent.
+  Connects to an IRC server and relays messages between an IRC channel
+  (or DMs) and the Hermes agent.  No external dependencies — uses
+  Python's stdlib asyncio for the IRC protocol.
+author: Nous Research
+# ``requires_env`` entries are surfaced in ``hermes config`` UI via the
+# platform-plugin env var injector in ``hermes_cli/config.py``.
+requires_env:
+  - name: IRC_SERVER
+    description: "IRC server hostname (e.g. irc.libera.chat)"
+    prompt: "IRC server"
+    password: false
+  - name: IRC_CHANNEL
+    description: "Channel to join (e.g. #hermes — comma-separate for multiple)"
+    prompt: "IRC channel"
+    password: false
+  - name: IRC_NICKNAME
+    description: "Bot nickname on IRC (default: hermes-bot)"
+    prompt: "Bot nickname"
+    password: false
+optional_env:
+  - name: IRC_PORT
+    description: "IRC server port (default: 6697 with TLS, 6667 without)"
+    prompt: "IRC port"
+    password: false
+  - name: IRC_USE_TLS
+    description: "Use TLS for the IRC connection (1/true/yes to enable, default: true on port 6697)"
+    prompt: "Use TLS? (true/false)"
+    password: false
+  - name: IRC_SERVER_PASSWORD
+    description: "Server password for the IRC PASS command (optional)"
+    prompt: "Server password (optional)"
+    password: true
+  - name: IRC_NICKSERV_PASSWORD
+    description: "NickServ password for automatic IDENTIFY on connect (optional)"
+    prompt: "NickServ password (optional)"
+    password: true
+  - name: IRC_ALLOWED_USERS
+    description: "Comma-separated IRC nicks allowed to talk to the bot"
+    prompt: "Allowed nicks (comma-separated)"
+    password: false
+  - name: IRC_ALLOW_ALL_USERS
+    description: "Allow anyone in the channel to talk to the bot (dev only)"
+    prompt: "Allow all users? (true/false)"
+    password: false
+  - name: IRC_HOME_CHANNEL
+    description: "Channel for cron / notification delivery (defaults to IRC_CHANNEL)"
+    prompt: "Home channel (or empty)"
+    password: false

plugins/platforms/line/__init__.py

@@ -0,0 +1,3 @@
+from .adapter import register
+
+__all__ = ["register"]

plugins/platforms/line/plugin.yaml

@@ -0,0 +1,65 @@
+name: line-platform
+label: LINE
+kind: platform
+version: 1.0.0
+description: >
+  LINE Messaging API gateway adapter for Hermes Agent.
+  Runs an aiohttp webhook server that receives LINE webhook events
+  (with HMAC-SHA256 signature verification) and relays messages between
+  LINE chats (1:1, groups, rooms) and the Hermes agent. Outbound replies
+  prefer the free reply token and fall back to the metered Push API
+  when the token has expired or is absent. Slow LLM responses surface a
+  Template Buttons postback bubble so the user can fetch the answer with
+  a fresh reply token (free) once it's ready.
+author: Hermes Agent contributors
+# ``requires_env`` and ``optional_env`` entries are surfaced in the
+# ``hermes config`` UI via the platform-plugin env var injector in
+# ``hermes_cli/config.py``.
+requires_env:
+  - name: LINE_CHANNEL_ACCESS_TOKEN
+    description: "LINE channel long-lived access token (LINE Developers Console > Messaging API > Channel access token)"
+    prompt: "LINE channel access token"
+    url: "https://developers.line.biz/console/"
+    password: true
+  - name: LINE_CHANNEL_SECRET
+    description: "LINE channel secret (used for HMAC-SHA256 webhook signature verification)"
+    prompt: "LINE channel secret"
+    url: "https://developers.line.biz/console/"
+    password: true
+optional_env:
+  - name: LINE_PORT
+    description: "Webhook listen port (default: 8646)"
+    prompt: "Webhook port"
+    password: false
+  - name: LINE_HOST
+    description: "Webhook bind host (default: 0.0.0.0)"
+    prompt: "Webhook host"
+    password: false
+  - name: LINE_PUBLIC_URL
+    description: "Public HTTPS base URL for serving images/audio/video to LINE (e.g. https://my-tunnel.example.com). Required for media sending when the bind address is not directly reachable."
+    prompt: "Public HTTPS base URL"
+    password: false
+  - name: LINE_ALLOWED_USERS
+    description: "Comma-separated LINE user IDs allowed to DM the bot (U-prefixed)"
+    prompt: "Allowed user IDs (comma-separated)"
+    password: false
+  - name: LINE_ALLOWED_GROUPS
+    description: "Comma-separated LINE group IDs the bot will respond in (C-prefixed)"
+    prompt: "Allowed group IDs (comma-separated)"
+    password: false
+  - name: LINE_ALLOWED_ROOMS
+    description: "Comma-separated LINE room IDs the bot will respond in (R-prefixed)"
+    prompt: "Allowed room IDs (comma-separated)"
+    password: false
+  - name: LINE_ALLOW_ALL_USERS
+    description: "Allow any LINE user to talk to the bot (dev only — disables allowlist)"
+    prompt: "Allow all users? (true/false)"
+    password: false
+  - name: LINE_HOME_CHANNEL
+    description: "Default user/group/room ID for cron / notification delivery"
+    prompt: "Home channel ID (or empty)"
+    password: false
+  - name: LINE_SLOW_RESPONSE_THRESHOLD
+    description: "Seconds before the slow-LLM postback button fires (default: 45; set 0 to disable and always Push-fallback)"
+    prompt: "Slow response threshold (seconds)"
+    password: false

plugins/platforms/mattermost/__init__.py

@@ -0,0 +1,3 @@
+from .adapter import register
+
+__all__ = ["register"]

plugins/platforms/mattermost/plugin.yaml

@@ -0,0 +1,49 @@
+name: mattermost-platform
+label: Mattermost
+kind: platform
+version: 1.0.0
+description: >
+  Mattermost gateway adapter for Hermes Agent.
+  Connects to a self-hosted or cloud Mattermost instance via the v4 REST
+  API + WebSocket event stream and relays messages between Mattermost
+  channels/DMs and the Hermes agent. Supports thread-mode replies, native
+  file uploads, channel-scoped allowlists, and home-channel cron delivery.
+author: NousResearch
+requires_env:
+  - name: MATTERMOST_URL
+    description: "Mattermost server URL (e.g. https://mm.example.com)"
+    prompt: "Mattermost server URL"
+    password: false
+  - name: MATTERMOST_TOKEN
+    description: "Bot account token or personal-access token"
+    prompt: "Mattermost bot token"
+    password: true
+optional_env:
+  - name: MATTERMOST_ALLOWED_USERS
+    description: "Comma-separated Mattermost user IDs allowed to talk to the bot"
+    prompt: "Allowed users (comma-separated)"
+    password: false
+  - name: MATTERMOST_ALLOW_ALL_USERS
+    description: "Allow any Mattermost user to trigger the bot (dev only)"
+    prompt: "Allow all users? (true/false)"
+    password: false
+  - name: MATTERMOST_HOME_CHANNEL
+    description: "Default channel ID for cron / notification delivery"
+    prompt: "Home channel ID"
+    password: false
+  - name: MATTERMOST_REPLY_MODE
+    description: "How replies are sent: 'thread' (nested) or 'off' (flat). Default: off."
+    prompt: "Reply mode (thread|off)"
+    password: false
+  - name: MATTERMOST_REQUIRE_MENTION
+    description: "Require @bot mention in channels (default true). Set false for free-response everywhere."
+    prompt: "Require @mention? (true/false)"
+    password: false
+  - name: MATTERMOST_FREE_RESPONSE_CHANNELS
+    description: "Comma-separated channel IDs where @mention is not required."
+    prompt: "Free-response channel IDs (comma-separated)"
+    password: false
+  - name: MATTERMOST_ALLOWED_CHANNELS
+    description: "If set, the bot only responds in these channels (whitelist)."
+    prompt: "Allowed channel IDs (comma-separated)"
+    password: false

plugins/platforms/ntfy/__init__.py

@@ -0,0 +1,3 @@
+from .adapter import register
+
+__all__ = ["register"]

plugins/platforms/ntfy/adapter.py

@@ -0,0 +1,593 @@
+"""ntfy platform adapter (Hermes plugin).
+
+Subscribes to a topic on ntfy.sh or any self-hosted ntfy server via
+HTTP streaming (``/json`` endpoint with ``poll=false``) and publishes
+replies via HTTP POST. No external SDK — only httpx, which is already
+a Hermes dependency.
+
+This adapter ships as a Hermes platform plugin under
+``plugins/platforms/ntfy/``. The Hermes plugin loader scans the
+directory at startup, calls :func:`register`, and the platform becomes
+available to ``gateway/run.py`` and ``tools/send_message_tool`` through
+the registry — no edits to core files required.
+
+Configuration in config.yaml::
+
+    platforms:
+      ntfy:
+        enabled: true
+        extra:
+          server: "https://ntfy.sh"       # or self-hosted URL
+          topic: "hermes-in"              # subscribe topic (incoming)
+          publish_topic: "hermes-out"     # optional — defaults to topic
+          token: "..."                    # optional Bearer / Basic auth token
+          markdown: true                  # optional — enable markdown (default: false)
+
+Environment variables (all read at adapter construct time, env wins over
+config.yaml ``extra``):
+
+    NTFY_TOPIC                 Topic to subscribe to (required)
+    NTFY_SERVER_URL            Server URL (default: https://ntfy.sh)
+    NTFY_TOKEN                 Bearer token or 'user:pass' for Basic auth
+    NTFY_PUBLISH_TOPIC         Reply topic (defaults to NTFY_TOPIC)
+    NTFY_MARKDOWN              "true"/"1"/"yes" enables X-Markdown header
+    NTFY_ALLOWED_USERS         Allowlist (treated by gateway as user IDs;
+                               on ntfy these are topic names)
+    NTFY_ALLOW_ALL_USERS       Allow any topic — dev only
+    NTFY_HOME_CHANNEL          Default topic for cron / notification delivery
+    NTFY_HOME_CHANNEL_NAME     Human label for the home channel
+
+Identity model: ntfy has no native authenticated user identity. The
+``title`` field is publisher-controlled and is NOT used for
+authorization. Each topic is treated as a single trusted channel —
+``user_id`` is fixed to the topic name. Use a private topic protected
+by a read token for any real trust boundary.
+"""
+
+import asyncio
+import json
+import logging
+import os
+import time
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+try:
+    import httpx
+    HTTPX_AVAILABLE = True
+except ImportError:
+    HTTPX_AVAILABLE = False
+    httpx = None  # type: ignore[assignment]
+
+from gateway.config import Platform, PlatformConfig
+from gateway.platforms.base import (
+    BasePlatformAdapter,
+    MessageEvent,
+    MessageType,
+    SendResult,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class _FatalStreamError(Exception):
+    """Raised when a stream error is unrecoverable (e.g. 401, 404)."""
+
+
+DEFAULT_SERVER = "https://ntfy.sh"
+MAX_MESSAGE_LENGTH = 4096  # ntfy message body limit
+DEDUP_WINDOW_SECONDS = 300
+DEDUP_MAX_SIZE = 1000
+RECONNECT_BACKOFF = [2, 5, 10, 30, 60]
+STREAM_TIMEOUT_SECONDS = 90  # ntfy keepalive default is 55s; give margin
+_ECHO_TAG = "hermes-agent"  # tag added to outgoing messages for echo-loop prevention
+
+
+def _build_auth_header(token: str) -> Dict[str, str]:
+    """Build an ``Authorization`` header from an ntfy token.
+
+    Shared by :class:`NtfyAdapter._auth_headers` and :func:`_standalone_send`
+    so both paths follow the same auth shape and whitespace-stripping rules.
+
+    Tokens are stripped of surrounding whitespace — pasted tokens often
+    carry trailing newlines that would otherwise render the header
+    malformed (``Authorization: Bearer foo\\n``).  ``user:pass`` tokens
+    become Basic auth; anything else is treated as a Bearer token.
+    Returns ``{}`` when no token is configured.
+    """
+    if not token:
+        return {}
+    token = token.strip()
+    if not token:
+        return {}
+    if ":" in token:
+        import base64
+        encoded = base64.b64encode(token.encode()).decode()
+        return {"Authorization": f"Basic {encoded}"}
+    return {"Authorization": f"Bearer {token}"}
+
+
+def _truncate_body(message: str, *, context: str) -> bytes:
+    """Apply the ntfy 4096-char limit, logging a warning on truncation.
+
+    ``context`` is included in the log message so adapter and standalone
+    truncations can be told apart in logs.
+    """
+    if len(message) > MAX_MESSAGE_LENGTH:
+        logger.warning(
+            "%s: truncating message from %d to %d chars (ntfy limit)",
+            context, len(message), MAX_MESSAGE_LENGTH,
+        )
+    return message[:MAX_MESSAGE_LENGTH].encode("utf-8")
+
+
+def check_requirements() -> bool:
+    """Check whether the ntfy adapter is installable and minimally configured.
+
+    Reads ``NTFY_TOPIC`` directly to avoid the cost of a full
+    ``load_gateway_config()`` (which also writes to ``os.environ``) on
+    every pre-flight check.
+    """
+    if not HTTPX_AVAILABLE:
+        return False
+    topic = os.getenv("NTFY_TOPIC", "").strip()
+    return bool(topic)
+
+
+def validate_config(config) -> bool:
+    """Validate that the configured ntfy platform has a topic set."""
+    extra = getattr(config, "extra", {}) or {}
+    topic = extra.get("topic") or os.getenv("NTFY_TOPIC", "")
+    return bool(topic)
+
+
+def is_connected(config) -> bool:
+    """Check whether ntfy is configured (env or config.yaml)."""
+    extra = getattr(config, "extra", {}) or {}
+    topic = os.getenv("NTFY_TOPIC") or extra.get("topic", "")
+    return bool(topic)
+
+
+class NtfyAdapter(BasePlatformAdapter):
+    """ntfy adapter.
+
+    Subscribes to a topic via HTTP streaming (``/json`` endpoint) and
+    publishes replies via HTTP POST. No external SDK — only httpx.
+    """
+
+    MAX_MESSAGE_LENGTH = MAX_MESSAGE_LENGTH
+
+    def __init__(self, config: PlatformConfig):
+        platform = Platform("ntfy")
+        super().__init__(config=config, platform=platform)
+
+        extra = config.extra or {}
+        self._server: str = (
+            extra.get("server")
+            or os.getenv("NTFY_SERVER_URL", DEFAULT_SERVER)
+        ).rstrip("/")
+        self._topic: str = extra.get("topic") or os.getenv("NTFY_TOPIC", "")
+        self._publish_topic: str = (
+            extra.get("publish_topic")
+            or os.getenv("NTFY_PUBLISH_TOPIC", "")
+            or self._topic
+        )
+        self._token: str = extra.get("token") or os.getenv("NTFY_TOKEN", "")
+
+        self._stream_task: Optional[asyncio.Task] = None
+        self._http_client: Optional["httpx.AsyncClient"] = None
+
+        # Message deduplication: msg_id -> timestamp
+        self._seen_messages: Dict[str, float] = {}
+
+    # -- Connection lifecycle -----------------------------------------------
+
+    async def connect(self) -> bool:
+        """Connect to ntfy by starting the streaming subscription task."""
+        if not HTTPX_AVAILABLE:
+            logger.warning("[%s] httpx not installed. Run: pip install httpx", self.name)
+            return False
+        if not self._topic:
+            logger.warning("[%s] NTFY_TOPIC not configured", self.name)
+            return False
+
+        try:
+            self._http_client = httpx.AsyncClient(timeout=None)
+            self._stream_task = asyncio.create_task(self._run_stream())
+            self._mark_connected()
+            logger.info("[%s] Connected — subscribing to %s/%s", self.name, self._server, self._topic)
+            return True
+        except Exception as e:
+            logger.error("[%s] Failed to connect: %s", self.name, e)
+            return False
+
+    async def _run_stream(self) -> None:
+        """Subscribe to the ntfy topic with automatic reconnection."""
+        backoff_idx = 0
+        stream_start: float = 0.0
+        url = f"{self._server}/{self._topic}/json"
+        headers = self._auth_headers()
+
+        while self._running:
+            try:
+                logger.debug("[%s] Opening stream to %s", self.name, url)
+                stream_start = time.monotonic()
+                await self._consume_stream(url, headers)
+            except asyncio.CancelledError:
+                return
+            except _FatalStreamError:
+                self._running = False
+                return
+            except Exception as e:
+                if not self._running:
+                    return
+                logger.warning("[%s] Stream error: %s", self.name, e)
+
+            if not self._running:
+                return
+
+            # Reset backoff if stream stayed alive for at least 60s
+            if time.monotonic() - stream_start >= 60.0:
+                backoff_idx = 0
+            delay = RECONNECT_BACKOFF[min(backoff_idx, len(RECONNECT_BACKOFF) - 1)]
+            logger.info("[%s] Reconnecting in %ds...", self.name, delay)
+            await asyncio.sleep(delay)
+            backoff_idx += 1
+
+    async def _consume_stream(self, url: str, headers: Dict[str, str]) -> None:
+        """Open an HTTP streaming connection and dispatch events."""
+        # poll=false keeps a persistent streaming connection alive with keepalive events
+        params = {"poll": "false"}
+        async with self._http_client.stream(
+            "GET",
+            url,
+            headers=headers,
+            params=params,
+            timeout=httpx.Timeout(connect=15.0, read=STREAM_TIMEOUT_SECONDS, write=15.0, pool=15.0),
+        ) as response:
+            if response.status_code == 401:
+                logger.error(
+                    "[%s] Authentication failed (401) — stopping reconnect loop. Check NTFY_TOKEN.",
+                    self.name,
+                )
+                self._set_fatal_error(
+                    "ntfy_unauthorized",
+                    "ntfy server rejected auth (401). Check NTFY_TOKEN.",
+                    retryable=False,
+                )
+                raise _FatalStreamError("401 Unauthorized")
+            if response.status_code == 404:
+                logger.error(
+                    "[%s] Topic not found (404): %s — stopping reconnect loop.",
+                    self.name, self._topic,
+                )
+                self._set_fatal_error(
+                    "ntfy_topic_not_found",
+                    f"ntfy topic '{self._topic}' returned 404. Check NTFY_TOPIC.",
+                    retryable=False,
+                )
+                raise _FatalStreamError("404 Not Found")
+            response.raise_for_status()
+
+            async for line in response.aiter_lines():
+                if not self._running:
+                    return
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    event = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if event.get("event") == "message":
+                    await self._on_message(event)
+
+    async def disconnect(self) -> None:
+        """Disconnect from ntfy."""
+        self._running = False
+        self._mark_disconnected()
+
+        if self._stream_task:
+            self._stream_task.cancel()
+            try:
+                await self._stream_task
+            except asyncio.CancelledError:
+                pass
+            self._stream_task = None
+
+        if self._http_client:
+            await self._http_client.aclose()
+            self._http_client = None
+
+        self._seen_messages.clear()
+        logger.info("[%s] Disconnected", self.name)
+
+    # -- Inbound message processing -----------------------------------------
+
+    async def _on_message(self, event: Dict[str, Any]) -> None:
+        """Process an incoming ntfy message event."""
+        msg_id = event.get("id") or uuid.uuid4().hex
+        if self._is_duplicate(msg_id):
+            logger.debug("[%s] Duplicate message %s, skipping", self.name, msg_id)
+            return
+
+        # Echo-loop prevention: skip messages tagged by this adapter.
+        tags = event.get("tags") or []
+        if _ECHO_TAG in tags:
+            logger.debug("[%s] Skipping own message (echo tag)", self.name)
+            return
+
+        text = (event.get("message") or "").strip()
+        if not text:
+            logger.debug("[%s] Empty message body, skipping", self.name)
+            return
+
+        topic = event.get("topic") or self._topic
+        # ntfy has no native authenticated user identity. The title field is
+        # publisher-controlled and must NOT be used for authorization — any
+        # publisher who knows the topic can set title to an allowed username.
+        # Treat ntfy as a single trusted channel; user_id is fixed to the
+        # topic name. NTFY_ALLOWED_USERS is only a real trust boundary when
+        # the topic itself is protected by a read token.
+        user_id = topic
+        user_name = topic
+
+        source = self.build_source(
+            chat_id=topic,
+            chat_name=topic,
+            chat_type="dm",
+            user_id=user_id,
+            user_name=user_name,
+        )
+
+        unix_ts = event.get("time")
+        try:
+            timestamp = (
+                datetime.fromtimestamp(int(unix_ts), tz=timezone.utc)
+                if unix_ts else datetime.now(tz=timezone.utc)
+            )
+        except (ValueError, OSError, TypeError):
+            timestamp = datetime.now(tz=timezone.utc)
+
+        message_event = MessageEvent(
+            text=text,
+            message_type=MessageType.TEXT,
+            source=source,
+            message_id=msg_id,
+            raw_message=event,
+            timestamp=timestamp,
+        )
+
+        logger.debug("[%s] Message on topic %s: %s", self.name, topic, text[:80])
+        await self.handle_message(message_event)
+
+    # -- Deduplication ------------------------------------------------------
+
+    def _is_duplicate(self, msg_id: str) -> bool:
+        """Return True if this message ID was already seen within the dedup window."""
+        now = time.time()
+        if len(self._seen_messages) > DEDUP_MAX_SIZE:
+            cutoff = now - DEDUP_WINDOW_SECONDS
+            self._seen_messages = {k: v for k, v in self._seen_messages.items() if v > cutoff}
+
+        if msg_id in self._seen_messages:
+            return True
+        self._seen_messages[msg_id] = now
+        return False
+
+    # -- Outbound messaging -------------------------------------------------
+
+    async def send(
+        self,
+        chat_id: str,
+        content: str,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        """Publish a message to the configured publish topic."""
+        metadata = metadata or {}
+        publish_topic = metadata.get("publish_topic") or self._publish_topic or chat_id
+
+        if not self._http_client:
+            return SendResult(success=False, error="HTTP client not initialized")
+
+        url = f"{self._server}/{publish_topic}"
+        markdown_enabled = (self.config.extra or {}).get("markdown", False)
+        headers = {
+            **self._auth_headers(),
+            "Content-Type": "text/plain; charset=utf-8",
+            "X-Tags": _ECHO_TAG,
+        }
+        if markdown_enabled:
+            headers["X-Markdown"] = "true"
+
+        if len(content) > self.MAX_MESSAGE_LENGTH:
+            logger.warning(
+                "[%s] Message truncated from %d to %d chars (ntfy limit)",
+                self.name, len(content), self.MAX_MESSAGE_LENGTH,
+            )
+        body = content[:self.MAX_MESSAGE_LENGTH]
+
+        try:
+            resp = await self._http_client.post(
+                url, content=body.encode("utf-8"), headers=headers, timeout=15.0,
+            )
+            if resp.status_code < 300:
+                try:
+                    data = resp.json()
+                    returned_id = data.get("id") or uuid.uuid4().hex[:12]
+                except Exception:
+                    returned_id = uuid.uuid4().hex[:12]
+                return SendResult(success=True, message_id=returned_id)
+            body_text = resp.text
+            logger.warning("[%s] Send failed HTTP %d: %s", self.name, resp.status_code, body_text[:200])
+            return SendResult(success=False, error=f"HTTP {resp.status_code}: {body_text[:200]}")
+        except httpx.TimeoutException:
+            return SendResult(success=False, error="Timeout publishing to ntfy")
+        except Exception as e:
+            logger.error("[%s] Send error: %s", self.name, e)
+            return SendResult(success=False, error=str(e))
+
+    async def send_typing(self, chat_id: str, metadata=None) -> None:
+        """ntfy does not support typing indicators."""
+        pass
+
+    async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
+        """Return basic info about an ntfy topic."""
+        return {"name": chat_id, "type": "dm"}
+
+    # -- Helpers ------------------------------------------------------------
+
+    def _auth_headers(self) -> Dict[str, str]:
+        """Build Authorization header if a token is configured."""
+        return _build_auth_header(self._token)
+
+
+# ---------------------------------------------------------------------------
+# Plugin registration
+# ---------------------------------------------------------------------------
+
+
+def _env_enablement() -> dict | None:
+    """Seed ``PlatformConfig.extra`` from env vars during gateway config load.
+
+    Called by the platform registry's env-enablement hook BEFORE adapter
+    construction, so ``gateway status`` and ``get_connected_platforms()``
+    reflect env-only configuration without instantiating the HTTP client.
+    Returns ``None`` when ntfy isn't minimally configured; the caller skips
+    auto-enabling.
+
+    The special ``home_channel`` key in the returned dict is handled by the
+    core hook — it becomes a proper ``HomeChannel`` dataclass on the
+    ``PlatformConfig`` rather than being merged into ``extra``.
+    """
+    topic = os.getenv("NTFY_TOPIC", "").strip()
+    if not topic:
+        return None
+    seed: dict = {
+        "topic": topic,
+        "server": os.getenv("NTFY_SERVER_URL", DEFAULT_SERVER).rstrip("/"),
+    }
+    publish_topic = os.getenv("NTFY_PUBLISH_TOPIC", "").strip()
+    if publish_topic:
+        seed["publish_topic"] = publish_topic
+    token = os.getenv("NTFY_TOKEN", "").strip()
+    if token:
+        seed["token"] = token
+    markdown = os.getenv("NTFY_MARKDOWN", "").strip().lower()
+    if markdown:
+        seed["markdown"] = markdown in ("1", "true", "yes")
+    home = os.getenv("NTFY_HOME_CHANNEL", "").strip() or topic
+    if home:
+        seed["home_channel"] = {
+            "chat_id": home,
+            "name": os.getenv("NTFY_HOME_CHANNEL_NAME", home),
+        }
+    return seed
+
+
+async def _standalone_send(
+    pconfig,
+    chat_id: str,
+    message: str,
+    *,
+    thread_id: Optional[str] = None,
+    media_files: Optional[List[str]] = None,
+    force_document: bool = False,
+) -> Dict[str, Any]:
+    """Out-of-process publish for cron / send_message_tool fallbacks.
+
+    Used by ``tools/send_message_tool._send_via_adapter`` and the cron
+    scheduler when the gateway runner is not in this process (e.g.
+    ``hermes cron`` running standalone). Without this hook,
+    ``deliver=ntfy`` cron jobs fail with ``No live adapter for platform``.
+
+    ``thread_id`` and ``media_files`` are accepted for signature parity
+    only — ntfy has no thread or attachment primitive. Markdown is
+    honored if ``NTFY_MARKDOWN`` is set OR ``pconfig.extra["markdown"]``
+    is True.
+    """
+    if not HTTPX_AVAILABLE:
+        return {"error": "ntfy standalone send: httpx not installed"}
+
+    extra = getattr(pconfig, "extra", {}) or {}
+    server = (
+        extra.get("server")
+        or os.getenv("NTFY_SERVER_URL", DEFAULT_SERVER)
+    ).rstrip("/")
+    publish_topic = (
+        chat_id
+        or extra.get("publish_topic")
+        or os.getenv("NTFY_PUBLISH_TOPIC", "").strip()
+        or extra.get("topic")
+        or os.getenv("NTFY_TOPIC", "").strip()
+    )
+    if not publish_topic:
+        return {"error": "ntfy standalone send: NTFY_TOPIC not configured"}
+
+    token = extra.get("token") or os.getenv("NTFY_TOKEN", "")
+    markdown_env = os.getenv("NTFY_MARKDOWN", "").strip().lower()
+    markdown_enabled = bool(extra.get("markdown")) or markdown_env in ("1", "true", "yes")
+
+    headers = {"Content-Type": "text/plain; charset=utf-8", "X-Tags": _ECHO_TAG, **_build_auth_header(token)}
+    if markdown_enabled:
+        headers["X-Markdown"] = "true"
+
+    body = _truncate_body(message, context="ntfy standalone")
+
+    url = f"{server}/{publish_topic}"
+    try:
+        async with httpx.AsyncClient(timeout=15.0) as client:
+            resp = await client.post(url, content=body, headers=headers)
+        if resp.status_code >= 300:
+            return {"error": f"ntfy HTTP {resp.status_code}: {resp.text[:200]}"}
+        try:
+            data = resp.json()
+            msg_id = data.get("id") or uuid.uuid4().hex[:12]
+        except Exception:
+            msg_id = uuid.uuid4().hex[:12]
+        return {"success": True, "platform": "ntfy", "chat_id": publish_topic, "message_id": msg_id}
+    except Exception as e:
+        return {"error": f"ntfy standalone send failed: {e}"}
+
+
+def register(ctx) -> None:
+    """Plugin entry point — called by the Hermes plugin system at startup."""
+    ctx.register_platform(
+        name="ntfy",
+        label="ntfy",
+        adapter_factory=lambda cfg: NtfyAdapter(cfg),
+        check_fn=check_requirements,
+        validate_config=validate_config,
+        is_connected=is_connected,
+        required_env=["NTFY_TOPIC"],
+        install_hint="pip install httpx   # already a Hermes dependency",
+        # Env-driven auto-configuration: seeds PlatformConfig.extra so
+        # env-only setups show up in `hermes gateway status` without
+        # instantiating the HTTP client.
+        env_enablement_fn=_env_enablement,
+        # Cron home-channel delivery support — `deliver=ntfy` cron jobs
+        # route to NTFY_HOME_CHANNEL when set.
+        cron_deliver_env_var="NTFY_HOME_CHANNEL",
+        # Out-of-process cron delivery. Without this hook, deliver=ntfy
+        # cron jobs fail with "No live adapter" when cron runs separately
+        # from the gateway.
+        standalone_sender_fn=_standalone_send,
+        # Auth env vars for _is_user_authorized() integration.
+        allowed_users_env="NTFY_ALLOWED_USERS",
+        allow_all_env="NTFY_ALLOW_ALL_USERS",
+        max_message_length=MAX_MESSAGE_LENGTH,
+        emoji="🔔",
+        # ntfy publishers have no persistent identity — topic names are
+        # the only identifier, no phone numbers / emails to redact.
+        pii_safe=True,
+        allow_update_command=True,
+        platform_hint=(
+            "You are communicating via ntfy push notifications. "
+            "Use plain text by default — ntfy supports optional markdown "
+            "(set markdown: true in config or NTFY_MARKDOWN=true). "
+            "Keep responses concise; ntfy is a push notification service "
+            "with a 4096-character per-message limit."
+        ),
+    )

plugins/platforms/ntfy/plugin.yaml

@@ -0,0 +1,56 @@
+name: ntfy-platform
+label: ntfy
+kind: platform
+version: 1.0.0
+description: >
+  ntfy push-notification gateway adapter for Hermes Agent.
+  Subscribes to a topic on ntfy.sh or any self-hosted ntfy server via
+  HTTP streaming, and publishes replies via HTTP POST. Lightweight —
+  no external SDK, only httpx (already a Hermes dependency).
+
+  ntfy has no native user-identity primitive; the adapter treats each
+  topic as a single trusted channel and never derives user identity
+  from publisher-controlled fields. Use a private topic + read token
+  for any real trust boundary.
+author: sprmn24
+# ``requires_env`` and ``optional_env`` entries are surfaced in the
+# ``hermes config`` UI via the platform-plugin env var injector in
+# ``hermes_cli/config.py``.
+requires_env:
+  - name: NTFY_TOPIC
+    description: "Topic name to subscribe to (e.g. hermes-in)"
+    prompt: "ntfy subscribe topic"
+    password: false
+optional_env:
+  - name: NTFY_SERVER_URL
+    description: "ntfy server URL (default: https://ntfy.sh)"
+    prompt: "ntfy server URL"
+    password: false
+  - name: NTFY_TOKEN
+    description: "Bearer token or 'user:pass' for Basic auth (optional)"
+    prompt: "ntfy auth token (or empty)"
+    password: true
+  - name: NTFY_PUBLISH_TOPIC
+    description: "Topic to publish replies to (defaults to NTFY_TOPIC)"
+    prompt: "ntfy publish topic (or empty)"
+    password: false
+  - name: NTFY_MARKDOWN
+    description: "Send replies with X-Markdown: true header (true/false, default: false)"
+    prompt: "Enable markdown formatting? (true/false)"
+    password: false
+  - name: NTFY_ALLOWED_USERS
+    description: "Comma-separated topic names allowed (allowlist)"
+    prompt: "Allowed topic names (comma-separated)"
+    password: false
+  - name: NTFY_ALLOW_ALL_USERS
+    description: "Allow any topic to talk to the bot (dev only — disables allowlist)"
+    prompt: "Allow all topics? (true/false)"
+    password: false
+  - name: NTFY_HOME_CHANNEL
+    description: "Default topic for cron / notification delivery"
+    prompt: "Home channel topic (or empty)"
+    password: false
+  - name: NTFY_HOME_CHANNEL_NAME
+    description: "Human label for the home channel (defaults to the topic name)"
+    prompt: "Home channel display name (or empty)"
+    password: false

plugins/platforms/photon/README.md

@@ -0,0 +1,174 @@
+# Photon iMessage platform plugin
+
+This plugin connects Hermes Agent to iMessage (and other Spectrum
+interfaces) through [Photon][photon] — a managed service that handles
+iMessage line allocation, delivery, and abuse-prevention so users don't
+have to run their own Mac relay.
+
+The free tier uses Photon's shared iMessage line pool and is the path we
+recommend for everyone who doesn't already pay for a dedicated number.
+
+## Architecture
+
+Like Discord and Slack, Photon is a **persistent-connection** channel — no
+public URL, no webhook, no signing secret. The `spectrum-ts` SDK holds a
+long-lived **gRPC stream** to Photon for both directions. Because the SDK is
+TypeScript-only, Hermes runs it inside a small supervised Node sidecar and
+talks to it over loopback.
+
+```
+                         gRPC (spectrum-ts)
+┌─────────────────────────┐ ◄───────────────► ┌──────────────────────┐
+│  Photon Spectrum cloud  │   app.messages    │  Node sidecar        │
+│  (iMessage line owner)  │   space.send()    │  (plugins/…/sidecar) │
+└─────────────────────────┘                   └──────────┬───────────┘
+                                       GET /inbound (NDJSON) │  ▲ POST /send
+                                       inbound events        ▼  │ /typing
+                                              ┌──────────────────────┐
+                                              │  PhotonAdapter        │
+                                              │  (Python, in gateway) │
+                                              └──────────────────────┘
+```
+
+- **Inbound**: the sidecar consumes the SDK's `app.messages` gRPC stream,
+  normalizes each message, and streams it to the adapter over a loopback
+  `GET /inbound` (NDJSON). The adapter dedupes on `messageId` and dispatches
+  a `MessageEvent` to the gateway. It reconnects automatically if the stream
+  drops; the sidecar owns the gRPC reconnect to Photon.
+- **Outbound**: `send` / `send_typing` / reaction tapbacks are loopback POSTs
+  to the sidecar (`/send`, `/send-attachment`, `/typing`, `/react`,
+  `/unreact`), authenticated with a shared `X-Hermes-Sidecar-Token`.
+
+## First-time setup
+
+```bash
+# One-shot setup: device login (opens browser) + project + user + sidecar deps
+hermes photon setup --phone +15551234567
+
+# Start the gateway
+hermes gateway start
+```
+
+`hermes photon setup` does, in order:
+
+1. **Device login** (RFC 8628, `client_id=photon-cli`) — opens
+   `https://app.photon.codes/` for approval and stores the bearer token.
+2. **Find or create** the `Hermes Agent` project on the Photon dashboard.
+3. **Enable Spectrum**, read the project's `spectrumProjectId`, rotate the
+   project secret, and persist both.
+4. **Register your phone number** as a Spectrum user (idempotent — skipped if
+   a user with that number already exists).
+5. **Print the assigned iMessage line** — the number you text to reach your
+   agent.
+6. **Install the sidecar deps** (`npm ci` — installs the committed lockfile
+   verbatim, so every setup runs the exact `spectrum-ts` version this plugin
+   was written against).
+
+There is no separate `login` command; like every other Hermes channel,
+onboarding goes through one setup surface. Re-running `setup` reuses an
+existing token/project, so it's safe to run again to finish a partial setup.
+Run `hermes photon status` to see what's configured.
+
+## Credentials
+
+Runtime SDK credentials live in `~/.hermes/.env` (the same place every other
+channel keeps its token), and the adapter reads them from the environment:
+
+```bash
+PHOTON_PROJECT_ID=<spectrumProjectId>   # the SDK's projectId
+PHOTON_PROJECT_SECRET=<projectSecret>
+```
+
+Management metadata lives in `~/.hermes/auth.json` under `credential_pool`:
+
+```jsonc
+{
+  "credential_pool": {
+    "photon": [
+      { "access_token": "<device-bearer>", "issued_at": ... }
+    ],
+    "photon_project": [
+      {
+        "dashboard_project_id": "<dashboard id>",
+        "spectrum_project_id": "<spectrumProjectId>",
+        "project_secret": "<projectSecret>",
+        "name": "Hermes Agent"
+      }
+    ]
+  }
+}
+```
+
+> **Note on ids.** A Photon project has two identifiers: the dashboard `id`
+> (used for management API calls) and the `spectrumProjectId` (what the SDK
+> authenticates with). `PHOTON_PROJECT_ID` is the **spectrum** id.
+
+## Configuration knobs
+
+All env vars are documented in `plugin.yaml`. The most important:
+
+| Env var                   | Default                    | Meaning                              |
+|---------------------------|----------------------------|--------------------------------------|
+| `PHOTON_PROJECT_ID`       | from .env / auth.json      | Spectrum project id (SDK `projectId`)|
+| `PHOTON_PROJECT_SECRET`   | from .env / auth.json      | Project secret                       |
+| `PHOTON_SIDECAR_PORT`     | 8789                       | Loopback port for the sidecar        |
+| `PHOTON_SIDECAR_AUTOSTART`| true                       | Spawn the sidecar on connect         |
+| `PHOTON_DASHBOARD_HOST`   | https://app.photon.codes   | Dashboard API host                   |
+| `PHOTON_SPECTRUM_HOST`    | https://spectrum.photon.codes | Spectrum API host                 |
+| `PHOTON_HOME_CHANNEL`     | your number (set by setup) | Default space for cron delivery — a space id, or a bare E.164 number (resolved to a DM) |
+| `PHOTON_ALLOWED_USERS`    | your number (set by setup) | Comma-separated E.164 allowlist      |
+| `PHOTON_REQUIRE_MENTION`  | false                      | Gate group chats on a wake word      |
+| `PHOTON_MAX_INLINE_ATTACHMENT_BYTES` | 20 MB           | Max inbound attachment size the sidecar reads & inlines |
+| `PHOTON_TELEMETRY`        | false                      | Spectrum SDK telemetry — toggle with `hermes photon telemetry on\|off` (restart the gateway to apply) |
+| `PHOTON_MARKDOWN`         | true                       | Send agent replies as markdown (iMessage renders natively). `false` strips formatting to plain text |
+| `PHOTON_REACTIONS`        | false                      | Tapback 👀/👍/👎 as processing status; tapbacks on bot messages reach the agent as `reaction:added:<emoji>` |
+
+## Attachments & limitations
+
+- **Inbound attachments and voice notes are downloaded.** The sidecar reads
+  the bytes (`content.read()`) and base64-inlines them on the NDJSON event; the
+  adapter caches them to the shared media cache and populates `media_urls` /
+  `media_types`, so the agent sees the real image/file or can transcribe the
+  voice note — parity with the BlueBubbles iMessage channel. Media larger than
+  `PHOTON_MAX_INLINE_ATTACHMENT_BYTES` (default 20 MB), or any byte read that
+  fails, falls back to a text marker (`[Photon attachment received: …]` or
+  `[Photon voice received: …]`) so the agent still knows something arrived.
+- **Outbound attachments are supported.** Images, voice notes, video, and
+  documents are sent via `space.send(attachment(...))` /
+  `space.send(voice(...))` through the sidecar's `/send-attachment`
+  endpoint; a caption is delivered as a separate text bubble after the media.
+- **Markdown is rendered.** Replies go out via spectrum-ts' `markdown()`
+  builder; iMessage renders bold/italics/lists/code natively and other
+  Spectrum platforms degrade to readable plain text. `PHOTON_MARKDOWN=false`
+  reverts to stripped plain text.
+- **Reactions (tapbacks) are supported** behind `PHOTON_REACTIONS` (default
+  off): the adapter tapbacks 👀 while processing and swaps it for 👍/👎 on
+  completion, and a user tapback on a bot-sent message is routed to the agent
+  as a synthetic `reaction:added:<emoji>` event. Removal after a sidecar
+  restart is best-effort — the live reaction handle is lost, so a stale
+  tapback heals when the next reaction replaces it. Group spaces stay
+  reachable across restarts via spectrum-ts v3's `space.get(id)`.
+- **Message effects, polls** — supported by `spectrum-ts` but not yet
+  exposed; the sidecar is the natural place to add them.
+
+## Upgrading spectrum-ts
+
+`spectrum-ts` is pinned to an **exact version** in `sidecar/package.json`
+(no `^` range) and installed with `npm ci`, because the SDK ships breaking
+majors (v2 removed `defineFusorPlatform`; v3 reworked space construction).
+A floating range or `npm install spectrum-ts@latest` would let a breaking
+release take down fresh setups silently. Upgrades are deliberate:
+
+1. Read the [SDK release notes](https://github.com/photon-hq/spectrum-ts/releases)
+   for every version between the current pin and the target.
+2. Bump the exact pin in `sidecar/package.json`, then run `npm install`
+   inside `sidecar/` to regenerate `package-lock.json`. Commit both.
+3. Migrate `sidecar/index.mjs` against the new typings
+   (`sidecar/node_modules/spectrum-ts/dist/*.d.ts` is the source of truth —
+   the hosted docs can lag).
+4. Run `pytest tests/plugins/platforms/photon/`.
+5. Verify end-to-end: `hermes photon status`, a DM and a group roundtrip,
+   and an agent reply into a group right after a gateway restart (exercises
+   `space.get` rehydration).
+
+[photon]: https://photon.codes/

plugins/platforms/photon/__init__.py

@@ -0,0 +1,4 @@
+"""Photon Spectrum (iMessage) platform plugin entry point."""
+from .adapter import register
+
+__all__ = ["register"]

plugins/platforms/photon/cli.py

@@ -0,0 +1,441 @@
+"""
+``hermes photon ...`` CLI subcommands — registered by the plugin via
+``ctx.register_cli_command()``.
+
+Subcommands:
+
+    setup              full first-time setup (device login + project + user + sidecar)
+    status             show login + project + sidecar dep state
+    install-sidecar    npm install inside plugins/platforms/photon/sidecar/
+    telemetry          show or toggle Spectrum SDK telemetry (on/off)
+
+The device-code login runs automatically as the first step of ``setup``;
+there is no standalone ``login`` verb (matching how every other Hermes
+gateway channel onboards through a single setup surface).
+
+Photon uses the spectrum-ts gRPC stream for inbound — there is no webhook
+to register, so there are no webhook subcommands.
+"""
+from __future__ import annotations
+
+import argparse
+import getpass
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from hermes_cli.colors import Colors, color
+
+from . import auth as photon_auth
+
+_SIDECAR_DIR = Path(__file__).parent / "sidecar"
+
+
+# ---------------------------------------------------------------------------
+# argparse wiring
+
+def register_cli(parser: argparse.ArgumentParser) -> None:
+    """Wire up `hermes photon ...` subcommands."""
+    subs = parser.add_subparsers(dest="photon_command", required=False)
+
+    p_setup = subs.add_parser(
+        "setup",
+        help="First-time setup (device login + project + user + sidecar)",
+    )
+    p_setup.add_argument("--project-name", default=None,
+                         help="Project name (default: 'Hermes Agent')")
+    p_setup.add_argument("--phone", default=None,
+                         help="Your E.164 phone number (e.g. +15551234567)")
+    p_setup.add_argument("--first-name", default=None)
+    p_setup.add_argument("--last-name", default=None)
+    p_setup.add_argument("--email", default=None)
+    p_setup.add_argument("--no-browser", action="store_true",
+                         help="Don't try to open a browser for device login; print the URL only")
+    p_setup.add_argument("--skip-sidecar-install", action="store_true",
+                         help="Skip `npm install` inside the sidecar directory")
+
+    subs.add_parser("status", help="Show login + project + sidecar dep state")
+    subs.add_parser("install-sidecar", help="Run npm install inside the sidecar directory")
+
+    p_telemetry = subs.add_parser(
+        "telemetry",
+        help="Show or toggle Spectrum SDK telemetry (on/off)",
+    )
+    p_telemetry.add_argument(
+        "state", nargs="?", choices=("on", "off"),
+        help="Turn telemetry on or off (omit to show the current state)",
+    )
+
+    parser.set_defaults(func=dispatch)
+
+
+# ---------------------------------------------------------------------------
+# Dispatch
+
+def dispatch(args: argparse.Namespace) -> int:
+    sub = getattr(args, "photon_command", None)
+    if sub is None:
+        # No subcommand given — show status by default.
+        return _cmd_status(args)
+    if sub == "setup":
+        return _cmd_setup(args)
+    if sub == "status":
+        return _cmd_status(args)
+    if sub == "install-sidecar":
+        return _cmd_install_sidecar(args)
+    if sub == "telemetry":
+        return _cmd_telemetry(args)
+    print(f"unknown subcommand: {sub}", file=sys.stderr)
+    return 2
+
+
+# ---------------------------------------------------------------------------
+# Subcommand handlers
+
+def _run_device_login(args: argparse.Namespace) -> int:
+    """Run the RFC 8628 device-code login flow and persist the token.
+
+    Internal helper — invoked as the first step of ``setup``. There is
+    no standalone ``hermes photon login`` command; Photon onboards
+    through the single ``setup`` surface like every other channel.
+    """
+    def _print_code(code):
+        target = code.verification_uri_complete or code.verification_uri
+        print()
+        print("┌─ Photon device login ────────────────────────────────────────")
+        print(f"│  Open this URL:  {target}")
+        print(f"│  Enter the code: {code.user_code}")
+        print("│  (waiting for approval — Ctrl-C to cancel)")
+        print("└──────────────────────────────────────────────────────────────")
+        print()
+
+    try:
+        token = photon_auth.login_device_flow(
+            open_browser=not args.no_browser,
+            on_user_code=_print_code,
+        )
+    except Exception as e:
+        print(f"login failed: {e}", file=sys.stderr)
+        return 1
+    # Don't print any portion of the token — even a prefix can help a
+    # shoulder-surfer or accidentally leak into a screen recording.
+    _ = token
+    print(f"✓ logged in — token saved to {photon_auth._auth_json_path()}")
+    return 0
+
+
+def _cmd_setup(args: argparse.Namespace) -> int:
+    # 1. Login (skip if we already have a token).
+    token = photon_auth.load_photon_token()
+    if not token:
+        print("[1/5] No Photon token found — running device login...")
+        rc = _run_device_login(args)
+        if rc != 0:
+            return rc
+        token = photon_auth.load_photon_token()
+        if not token:
+            print("login completed but token was not stored", file=sys.stderr)
+            return 1
+    else:
+        print("[1/5] Reusing existing Photon token")
+
+    # 2. Find or create the "Hermes Agent" project.
+    name = args.project_name or photon_auth.DEFAULT_PROJECT_NAME
+    dashboard_id = photon_auth.load_dashboard_project_id()
+    try:
+        if dashboard_id:
+            print("[2/5] Reusing configured Photon project")
+        else:
+            existing = photon_auth.find_project_by_name(token, name)
+            if existing and existing.get("id"):
+                dashboard_id = existing["id"]
+                print(f"[2/5] Found existing project '{name}'")
+            else:
+                print(f"[2/5] Creating Photon project '{name}'...")
+                created = photon_auth.create_project(token, name=name)
+                dashboard_id = created.get("id")
+                print("  ✓ project created")
+    except Exception as e:
+        print(f"project setup failed: {e}", file=sys.stderr)
+        return 1
+    if not dashboard_id:
+        print("could not resolve a Photon project id", file=sys.stderr)
+        return 1
+
+    # 3. Enable Spectrum, fetch the spectrum project id, rotate the secret,
+    #    and persist both (runtime creds -> ~/.hermes/.env, ids -> auth.json).
+    try:
+        print("[3/5] Enabling Spectrum and provisioning credentials...")
+        proj = photon_auth.ensure_spectrum_enabled(token, dashboard_id)
+        spectrum_id = proj.get("spectrumProjectId")
+        if not spectrum_id:
+            print("spectrum provisioning failed: no spectrum project id", file=sys.stderr)
+            return 1
+        spectrum_id = str(spectrum_id)
+        secret = photon_auth.regenerate_project_secret(token, dashboard_id)
+        photon_auth.store_project_credentials(
+            spectrum_project_id=spectrum_id,
+            project_secret=secret,
+            dashboard_project_id=dashboard_id,
+            name=name,
+        )
+        # spectrum_id is an opaque non-secret id; safe to show.
+        print(f"  ✓ Spectrum enabled (project id {spectrum_id}) — secret saved")
+    except Exception as e:
+        print(f"spectrum provisioning failed: {e}", file=sys.stderr)
+        return 1
+
+    # 4. Register the operator's phone number as a Spectrum user (idempotent).
+    phone = args.phone or _prompt(
+        color(
+            "[4/5] Your iMessage phone number (E.164, e.g. +15551234567): ",
+            Colors.CYAN,
+        )
+    )
+    agent_number = None
+    registered_phone = None
+    registered_user_id = None
+    if not phone:
+        print("      Skipped user registration (no phone given). Re-run with --phone later.")
+    else:
+        # Name/email are optional and never prompted for — pass --first-name /
+        # --email if you want them sent to the dashboard.
+        first_name = args.first_name
+        email = args.email
+        try:
+            user, created = photon_auth.register_user_if_absent(
+                spectrum_id, secret,
+                phone_number=phone,
+                first_name=first_name,
+                last_name=args.last_name,
+                email=email,
+            )
+        except ValueError as e:
+            print(f"      invalid phone number: {e}", file=sys.stderr)
+            return 1
+        except Exception as e:
+            print(f"      user registration failed: {e}", file=sys.stderr)
+            return 1
+        print("  ✓ phone registered" if created else "  ✓ phone already registered")
+        registered_phone = phone
+        registered_user_id = user.get("id")
+        # The number to text the agent is the user's assigned iMessage line
+        # (the dashboard's "TEXTS ON" column). On shared-number plans there is
+        # no dedicated entry in /lines, so this per-user field is the source of
+        # truth — and we already have it from the (reused) user object.
+        agent_number = photon_auth.user_assigned_line(user)
+        # Allowlist the operator and make their DM the cron home channel —
+        # otherwise the gateway denies their own inbound messages
+        # ("Unauthorized user") and has no default space for cron delivery.
+        _autoconfigure_access(phone)
+
+    # 5. Surface the agent's iMessage number (the number to text the agent).
+    if not agent_number:
+        # No per-user assignment — fall back to a dedicated line if the project
+        # has one provisioned in its line inventory.
+        try:
+            line = photon_auth.get_imessage_line(token, dashboard_id)
+            if line:
+                agent_number = line.get("phoneNumber")
+        except Exception as e:
+            print(f"      (could not fetch the assigned line: {e})", file=sys.stderr)
+    if agent_number:
+        print()
+        print(color("┌─ Your agent's iMessage number ───────────────────────────────", Colors.GREEN))
+        print(
+            color("│  📱 ", Colors.GREEN)
+            + color(str(agent_number), Colors.GREEN, Colors.BOLD)
+        )
+        print(color("│  Text this number from your phone to talk to your agent.", Colors.GREEN))
+        print(color("└──────────────────────────────────────────────────────────────", Colors.GREEN))
+    else:
+        print("      No iMessage line assigned yet — check the Photon dashboard.")
+    if registered_phone:
+        try:
+            photon_auth.store_user_numbers(
+                phone_number=registered_phone,
+                assigned_phone_number=agent_number,
+                user_id=str(registered_user_id) if registered_user_id else None,
+                dashboard_project_id=dashboard_id,
+            )
+        except Exception as e:
+            print(f"      (could not save Photon status metadata: {e})", file=sys.stderr)
+
+    # 6. Sidecar deps (spectrum-ts).
+    if args.skip_sidecar_install:
+        print("[5/5] Skipping sidecar npm install (--skip-sidecar-install)")
+    else:
+        print("[5/5] Installing Node sidecar deps (spectrum-ts)...")
+        rc = _install_sidecar()
+        if rc != 0:
+            return rc
+
+    print()
+    print("✓ Photon setup complete.")
+    print("  Start the gateway:  hermes gateway start")
+    return 0
+
+
+def _autoconfigure_access(phone: str) -> None:
+    """Allowlist the operator and set their DM as the cron home channel.
+
+    Writes ``PHOTON_ALLOWED_USERS`` (so the gateway authorizes the operator's
+    own inbound messages instead of denying them) and ``PHOTON_HOME_CHANNEL``
+    (the default space for cron delivery) to the operator's E.164 number. Each
+    is only filled when unset, so a hand-tuned allowlist / home channel is
+    never clobbered on a re-run.
+    """
+    try:
+        from hermes_cli.config import get_env_value, save_env_value
+    except ImportError:
+        return
+    for key, label in (
+        ("PHOTON_ALLOWED_USERS", "allowlisted your number"),
+        ("PHOTON_HOME_CHANNEL", "set your DM as the cron home channel"),
+    ):
+        try:
+            if get_env_value(key):
+                print(f"      {key} already set — leaving it as-is.")
+                continue
+            save_env_value(key, phone)
+            print(f"  ✓ {label} ({key})")
+        except Exception as e:
+            print(f"      could not set {key}: {e}", file=sys.stderr)
+
+
+def _cmd_status(_args: argparse.Namespace) -> int:
+    _refresh_status_numbers()
+    # Defer the credential rows to auth.print_credential_summary — its emit
+    # callback is the only sink that sees credential-derived strings, so
+    # cli.py keeps zero taint flow according to CodeQL.
+    photon_auth.print_credential_summary(print)
+    node_bin = os.getenv("PHOTON_NODE_BIN") or shutil.which("node")
+    sidecar_installed = (_SIDECAR_DIR / "node_modules").exists()
+    print(f"  node binary         : {node_bin or '✗ missing (install Node 18+)'}")
+    print(f"  sidecar deps        : {'✓ installed' if sidecar_installed else '✗ run `hermes photon install-sidecar`'}")
+    print(f"  telemetry           : {'on' if _telemetry_enabled() else 'off'} (`hermes photon telemetry on|off`)")
+    return 0
+
+
+def _refresh_status_numbers() -> None:
+    phone, assigned = photon_auth.load_user_numbers()
+    if phone and assigned:
+        return
+    spectrum_id, project_secret = photon_auth.load_project_credentials()
+    if not spectrum_id or not project_secret:
+        return
+    try:
+        photon_auth.refresh_user_numbers(spectrum_id, project_secret)
+    except Exception as e:
+        print(f"      (could not refresh Photon user numbers: {e})", file=sys.stderr)
+
+
+def _cmd_install_sidecar(_args: argparse.Namespace) -> int:
+    return _install_sidecar()
+
+
+def _telemetry_enabled() -> bool:
+    """Read PHOTON_TELEMETRY from the env / ~/.hermes/.env.
+
+    Mirrors the sidecar's truthy set (index.mjs) so the state shown here
+    always matches what the sidecar will actually do.
+    """
+    try:
+        from hermes_cli.config import get_env_value
+        raw = get_env_value("PHOTON_TELEMETRY")
+    except ImportError:
+        raw = os.getenv("PHOTON_TELEMETRY")
+    return (raw or "").strip().lower() in ("1", "true", "yes", "on")
+
+
+def _cmd_telemetry(args: argparse.Namespace) -> int:
+    state = getattr(args, "state", None)
+    if state is None:
+        print(f"Photon telemetry: {'on' if _telemetry_enabled() else 'off'}")
+        print("  Toggle with `hermes photon telemetry on` / `hermes photon telemetry off`.")
+        return 0
+    try:
+        from hermes_cli.config import save_env_value
+        save_env_value("PHOTON_TELEMETRY", "true" if state == "on" else "false")
+    except Exception as e:
+        print(f"could not save PHOTON_TELEMETRY: {e}", file=sys.stderr)
+        return 1
+    print(f"✓ Spectrum telemetry turned {state} (PHOTON_TELEMETRY in ~/.hermes/.env)")
+    print("  Restart the gateway for the sidecar to pick it up:  hermes gateway restart")
+    return 0
+
+
+def _install_sidecar() -> int:
+    npm = shutil.which("npm") or "npm"
+    if not shutil.which(npm):
+        print(
+            "npm is not on PATH. Install Node.js 18+ (https://nodejs.org/) "
+            "and re-run.",
+            file=sys.stderr,
+        )
+        return 1
+    # spectrum-ts is pinned exactly in package.json/package-lock.json because
+    # the SDK ships breaking majors (v2 removed defineFusorPlatform; v3
+    # reworked space construction). Upgrades are deliberate: bump the pin,
+    # migrate sidecar/index.mjs, re-run the photon tests — never `@latest`
+    # (see README "Upgrading spectrum-ts"). `npm ci` installs the committed
+    # lockfile verbatim; fall back to `npm install` when the lockfile is
+    # missing or drifted (e.g. a dev checkout mid-upgrade).
+    print(f"  $ cd {_SIDECAR_DIR} && {npm} ci")
+    proc = subprocess.run(  # noqa: S603
+        [npm, "ci"],
+        cwd=str(_SIDECAR_DIR),
+        check=False,
+    )
+    if proc.returncode != 0:
+        print(f"  npm ci failed — falling back to:  {npm} install")
+        proc = subprocess.run(  # noqa: S603
+            [npm, "install"],
+            cwd=str(_SIDECAR_DIR),
+            check=False,
+        )
+    if proc.returncode != 0:
+        print("npm install failed", file=sys.stderr)
+    return proc.returncode
+
+
+# ---------------------------------------------------------------------------
+# Gateway-setup entry point
+#
+# `hermes gateway setup` discovers platforms via the registry and calls each
+# entry's zero-arg ``setup_fn``. Photon registers this function so it appears
+# in the unified setup wizard alongside every other channel — same onboarding
+# surface, no Photon-specific detour. It runs the identical device-login +
+# project + user + sidecar flow as ``hermes photon setup`` with interactive
+# defaults (phone is prompted when stdin is a TTY).
+
+def gateway_setup() -> None:
+    """Run Photon first-time setup from the `hermes gateway setup` wizard."""
+    args = argparse.Namespace(
+        photon_command="setup",
+        project_name=None,
+        phone=None,
+        first_name=None,
+        last_name=None,
+        email=None,
+        no_browser=False,
+        skip_sidecar_install=False,
+    )
+    _cmd_setup(args)
+
+
+# ---------------------------------------------------------------------------
+# Small interactive helpers
+
+def _prompt(prompt: str, *, secret: bool = False) -> str:
+    if not sys.stdin.isatty():
+        return ""
+    try:
+        if secret:
+            return getpass.getpass(prompt).strip()
+        return input(prompt).strip()
+    except (KeyboardInterrupt, EOFError):
+        print()
+        return ""

plugins/platforms/photon/plugin.yaml

@@ -0,0 +1,88 @@
+name: photon-platform
+label: iMessage via Photon
+kind: platform
+version: 0.3.0
+description: >
+  Photon Spectrum gateway adapter for Hermes Agent.
+  Connects to iMessage (and other Spectrum interfaces) through Photon's
+  managed Spectrum platform. Both directions run over the `spectrum-ts`
+  SDK's long-lived gRPC stream via a small supervised Node sidecar —
+  inbound messages arrive on the SDK's `app.messages` stream (no webhook,
+  no public URL, no signing secret), and outbound messages are sent over
+  the same sidecar.
+
+  The plugin ships with a `hermes photon` CLI for the one-time device
+  login + project + user setup. Runtime credentials are written to
+  ``~/.hermes/.env`` (``PHOTON_PROJECT_ID`` = the Spectrum project id,
+  ``PHOTON_PROJECT_SECRET``) like every other channel, with management
+  metadata (device token, dashboard project id) in ``~/.hermes/auth.json``.
+  Photon's free shared-line model lets users get started without a paid plan.
+author: NousResearch
+requires_env:
+  - name: PHOTON_PROJECT_ID
+    description: "Spectrum project id (the project's spectrumProjectId; set by `hermes photon setup`)"
+    prompt: "Photon Spectrum project id"
+    url: "https://app.photon.codes/"
+    password: false
+  - name: PHOTON_PROJECT_SECRET
+    description: "Project secret paired with the Spectrum project id (set by `hermes photon setup`)"
+    prompt: "Photon project secret"
+    url: "https://app.photon.codes/"
+    password: true
+optional_env:
+  - name: PHOTON_SIDECAR_PORT
+    description: "Loopback port for the Node sidecar control + inbound channel (default 8789)"
+    prompt: "Sidecar control port"
+    password: false
+  - name: PHOTON_SIDECAR_AUTOSTART
+    description: "Spawn the Node sidecar on connect (true/false, default true)"
+    prompt: "Auto-start the sidecar?"
+    password: false
+  - name: PHOTON_NODE_BIN
+    description: "Path to the node binary (default: shutil.which('node'))"
+    prompt: "Node executable path"
+    password: false
+  - name: PHOTON_DASHBOARD_HOST
+    description: "Photon Dashboard API host (default https://app.photon.codes)"
+    prompt: "Dashboard host"
+    password: false
+  - name: PHOTON_SPECTRUM_HOST
+    description: "Photon Spectrum API host (default https://spectrum.photon.codes)"
+    prompt: "Spectrum API host"
+    password: false
+  - name: PHOTON_ALLOWED_USERS
+    description: "Comma-separated E.164 phone numbers allowed to talk to the bot"
+    prompt: "Allowed users (comma-separated)"
+    password: false
+  - name: PHOTON_ALLOW_ALL_USERS
+    description: "Allow any sender to trigger the bot (dev only — disables allowlist)"
+    prompt: "Allow all users? (true/false)"
+    password: false
+  - name: PHOTON_REQUIRE_MENTION
+    description: "Ignore group-chat messages unless they match a mention wake word (true/false, default false)"
+    prompt: "Require a mention in group chats?"
+    password: false
+  - name: PHOTON_MENTION_PATTERNS
+    description: "Mention wake-word regexes for group chats (JSON list or comma/newline-separated; defaults to Hermes wake words)"
+    prompt: "Group mention patterns"
+    password: false
+  - name: PHOTON_HOME_CHANNEL
+    description: "Default Photon target for cron / notification delivery: Spectrum space id, DM GUID, or bare E.164 phone number"
+    prompt: "Home Photon target"
+    password: false
+  - name: PHOTON_HOME_CHANNEL_NAME
+    description: "Human label for the home channel"
+    prompt: "Home channel display name"
+    password: false
+  - name: PHOTON_TELEMETRY
+    description: "Enable Spectrum SDK telemetry in the sidecar (true/false, default false; toggle with `hermes photon telemetry on|off`)"
+    prompt: "Enable Spectrum telemetry? (true/false)"
+    password: false
+  - name: PHOTON_MARKDOWN
+    description: "Send agent replies as markdown — iMessage renders it natively, other Spectrum platforms degrade to plain text (true/false, default true)"
+    prompt: "Render replies as markdown? (true/false)"
+    password: false
+  - name: PHOTON_REACTIONS
+    description: "Tapback 👀/👍/👎 on messages as processing status and route tapbacks on bot messages to the agent (true/false, default false)"
+    prompt: "Enable reaction tapbacks? (true/false)"
+    password: false

plugins/platforms/photon/sidecar/README.md

@@ -0,0 +1,52 @@
+# Photon sidecar
+
+Small Node helper that bridges Hermes Agent to Photon's Spectrum SDK
+(`spectrum-ts`).  Hermes is Python; Photon has no public HTTP
+send-message endpoint today; replies therefore go through this sidecar.
+
+The sidecar:
+
+- runs `Spectrum({ projectId, projectSecret, providers: [imessage.config()] })`
+- exposes a loopback-only HTTP control channel for the Python adapter
+  to push send/typing requests (auth via `X-Hermes-Sidecar-Token`)
+- drains the inbound message stream so `spectrum-ts` keeps its
+  reconnect/heartbeat machinery alive (real inbound delivery is via
+  Photon's signed webhook hitting our Python aiohttp server)
+
+## Install
+
+```bash
+cd plugins/platforms/photon/sidecar
+npm install
+```
+
+The Hermes plugin's `hermes photon setup` command runs `npm install`
+here automatically.
+
+## Run standalone
+
+For debugging:
+
+```bash
+PHOTON_PROJECT_ID=... PHOTON_PROJECT_SECRET=... \
+PHOTON_SIDECAR_PORT=8789 PHOTON_SIDECAR_TOKEN=$(openssl rand -hex 16) \
+node index.mjs
+```
+
+In normal use, the Python adapter supervises this process — start,
+restart on crash, kill on shutdown — and never asks the user to run
+it by hand.
+
+## Why a sidecar at all?
+
+Photon publishes webhooks (inbound) but their docs state explicitly:
+
+> Pass `space.id` to `Space.send(...)` from a separate `spectrum-ts`
+> SDK instance to reply.  No public HTTP send endpoint exists today.
+
+— https://photon.codes/docs/webhooks/events
+
+When Photon ships an HTTP send endpoint, the plan is to retire this
+sidecar entirely and call it directly from Python.  The plugin's
+outbound code path is already isolated behind a single helper
+(`_sidecar_send` in `adapter.py`) to make that swap a one-file change.

plugins/platforms/photon/sidecar/index.mjs

@@ -0,0 +1,690 @@
+// Hermes Agent — Photon Spectrum sidecar
+//
+// Spawned by `plugins/platforms/photon/adapter.py` to bridge BOTH directions
+// of messaging to Photon's Spectrum platform via the `spectrum-ts` SDK (the
+// SDK is TypeScript-only, so a Node sidecar is unavoidable — there is no
+// Python SDK and no public HTTP message API).
+//
+// Inbound  (gRPC -> Hermes): the SDK's `app.messages` async iterator is a
+//   long-lived gRPC stream. We serialize each `[space, message]` to a
+//   normalized JSON event and stream it to the Python adapter over a
+//   loopback `GET /inbound` (NDJSON). We pause pulling from the stream while
+//   no consumer is attached so a backlog isn't pulled-and-lost before the
+//   gateway connects.
+// Outbound (Hermes -> gRPC): `/send` drives `space.send(...)`; `/typing`
+//   sends the documented `typing("start" | "stop")` content builder.
+//
+// Protocol (all requests require `X-Hermes-Sidecar-Token: ${TOKEN}`):
+//   - GET  /inbound    -> 200 NDJSON stream; one JSON event per line, blank
+//                         lines are heartbeats. One consumer at a time.
+//   - POST /healthz     -> {"ok": true}
+//   - POST /send        -> {"ok": true, "messageId": "..."}
+//       body: {"spaceId": "...", "text": "...",
+//              "format": "text" | "markdown" (default "text")}
+//   - POST /send-attachment -> {"ok": true, "messageId": "..."}
+//       body: {"spaceId": "...", "path": "...", "name": "..." | null,
+//              "mimeType": "..." | null, "caption": "..." | null,
+//              "kind": "attachment" | "voice"}
+//   - POST /react       -> {"ok": true, "reactionId": "..." | null}
+//       body: {"spaceId": "...", "messageId": "<target msg id>",
+//              "emoji": "👀"}
+//   - POST /unreact     -> {"ok": true} | 400 soft failure
+//       body: {"spaceId": "...", "messageId": "<target msg id>",
+//              "reactionId": "..." | null (restart-recovery fallback)}
+//   - POST /typing      -> {"ok": true}
+//       body: {"spaceId": "...", "state": "start" | "stop"}
+//   - POST /shutdown    -> {"ok": true}; then process exits
+//
+// On SIGINT/SIGTERM the sidecar calls `app.stop()` (3s graceful) before
+// exiting. Logs go to stderr; Python supervises restart.
+//
+// Requires spectrum-ts 3.x — pinned exactly in package.json because the SDK
+// ships breaking majors; see README "Upgrading spectrum-ts".
+//
+// Env vars (required):
+//   PHOTON_PROJECT_ID      (== the project's spectrumProjectId)
+//   PHOTON_PROJECT_SECRET
+//   PHOTON_SIDECAR_PORT
+//   PHOTON_SIDECAR_TOKEN
+// Optional:
+//   PHOTON_SIDECAR_BIND    (default 127.0.0.1)
+//   PHOTON_SIDECAR_WATCH_STDIN  "1" = exit when stdin hits EOF (set by the
+//                          adapter, which holds our stdin pipe — parent-death
+//                          detection so a dead gateway can't orphan us)
+//   PHOTON_TELEMETRY       enable Spectrum SDK telemetry ("true"/"1"/"on"/"yes";
+//                          default off — toggle with `hermes photon telemetry`)
+
+import http from "node:http";
+import crypto from "node:crypto";
+import { once } from "node:events";
+
+const projectId = process.env.PHOTON_PROJECT_ID;
+const projectSecret = process.env.PHOTON_PROJECT_SECRET;
+const port = parseInt(process.env.PHOTON_SIDECAR_PORT || "8789", 10);
+const bind = process.env.PHOTON_SIDECAR_BIND || "127.0.0.1";
+const sharedToken = process.env.PHOTON_SIDECAR_TOKEN;
+const telemetry = /^(1|true|yes|on)$/i.test(
+  (process.env.PHOTON_TELEMETRY || "").trim()
+);
+
+// Inbound binary content is read into memory and base64-inlined on the NDJSON
+// event so the Python adapter can cache the real bytes (and the agent can see
+// images / transcribe voice). Cap the size we inline — above it we forward
+// metadata only and the adapter surfaces a text marker, so one large clip can't
+// balloon a single NDJSON line. Override via PHOTON_MAX_INLINE_ATTACHMENT_BYTES.
+const MAX_INLINE_ATTACHMENT_BYTES =
+  Number(process.env.PHOTON_MAX_INLINE_ATTACHMENT_BYTES) || 20 * 1024 * 1024;
+const DM_CHAT_GUID_RE = /^any;-;(\+\d{6,})$/;
+const E164_RE = /^\+\d{6,}$/;
+const MAX_KNOWN_SPACES = 2048;
+const MAX_KNOWN_MESSAGES = 1024;
+const MAX_REACTION_HANDLES = 512;
+
+if (!projectId || !projectSecret || !sharedToken) {
+  console.error(
+    "photon-sidecar: PHOTON_PROJECT_ID, PHOTON_PROJECT_SECRET and " +
+      "PHOTON_SIDECAR_TOKEN must all be set."
+  );
+  process.exit(2);
+}
+
+// Lazy-load spectrum-ts so a missing install fails with a clear message
+// instead of a cryptic module-resolution error during import.
+let Spectrum,
+  imessage,
+  attachment,
+  voice,
+  spectrumText,
+  spectrumMarkdown,
+  spectrumTyping;
+try {
+  ({
+    Spectrum,
+    attachment,
+    voice,
+    text: spectrumText,
+    markdown: spectrumMarkdown,
+    typing: spectrumTyping,
+  } = await import("spectrum-ts"));
+  ({ imessage } = await import("spectrum-ts/providers/imessage"));
+} catch (e) {
+  console.error(
+    "photon-sidecar: spectrum-ts is not installed. Run `npm install` " +
+      "inside plugins/platforms/photon/sidecar/. Original error: " +
+      (e && e.stack ? e.stack : String(e))
+  );
+  process.exit(3);
+}
+
+const app = await Spectrum({
+  projectId,
+  projectSecret,
+  providers: [imessage.config()],
+  options: { flattenGroups: true },
+  telemetry,
+});
+
+// ---------------------------------------------------------------------------
+// Inbound: forward `app.messages` (gRPC stream) to the Python consumer.
+
+// At most one Python consumer is attached at a time (the gateway adapter).
+let consumerRes = null;
+let consumerWaiters = [];
+const knownSpaces = new Map();
+// Inbound Message objects by id, so /react can usually skip a
+// `space.getMessage` round trip when tapping back on a recent message.
+const knownMessages = new Map();
+// One reaction handle per reacted-to message (key `${spaceId}\0${messageId}`,
+// value {emoji, handle}) — mirrors iMessage's one-tapback-per-sender
+// semantics; a new /react on the same target overwrites the slot. The handle
+// is the outbound reaction Message returned by `target.react()`, kept so
+// /unreact can `unsend()` it later.
+const reactionHandles = new Map();
+
+function lruSet(map, key, value, cap) {
+  if (map.has(key)) map.delete(key);
+  map.set(key, value);
+  if (map.size > cap) {
+    const oldest = map.keys().next().value;
+    if (oldest !== undefined) map.delete(oldest);
+  }
+}
+
+function rememberKnownSpace(id, space) {
+  if (!id || typeof id !== "string" || !space) return;
+  lruSet(knownSpaces, id, space, MAX_KNOWN_SPACES);
+}
+
+function rememberKnownMessage(message) {
+  const id = message?.id;
+  if (!id || typeof id !== "string") return;
+  lruSet(knownMessages, id, message, MAX_KNOWN_MESSAGES);
+}
+
+function phoneTargetFromSpaceId(spaceId) {
+  if (typeof spaceId !== "string") return null;
+  if (E164_RE.test(spaceId)) return spaceId;
+  const dmGuid = spaceId.match(DM_CHAT_GUID_RE);
+  return dmGuid ? dmGuid[1] : null;
+}
+
+function rememberInboundSpace(space, message) {
+  const msgSpace = message?.space || {};
+  const ids = [space?.id, msgSpace.id];
+  for (const id of ids) {
+    rememberKnownSpace(id, space);
+    const phone = phoneTargetFromSpaceId(id);
+    if (phone) rememberKnownSpace(phone, space);
+  }
+}
+
+function waitForConsumer() {
+  if (consumerRes) return Promise.resolve();
+  return new Promise((resolve) => consumerWaiters.push(resolve));
+}
+
+function setConsumer(res) {
+  consumerRes = res;
+  const waiters = consumerWaiters;
+  consumerWaiters = [];
+  for (const resolve of waiters) resolve();
+}
+
+function clearConsumer(res) {
+  if (consumerRes === res) consumerRes = null;
+}
+
+// Write one NDJSON line to the active consumer. Blocks until a consumer is
+// connected; if the write fails (consumer vanished mid-flight) we wait for a
+// new consumer and retry, so a message is never silently dropped here.
+async function deliver(line) {
+  for (;;) {
+    await waitForConsumer();
+    const res = consumerRes;
+    if (!res) continue;
+    try {
+      const flushed = res.write(line + "\n");
+      if (!flushed) await once(res, "drain");
+      return;
+    } catch {
+      clearConsumer(res);
+    }
+  }
+}
+
+async function normalizeBinaryContent(content) {
+  const meta = {
+    type: content.type,
+    id: content.id ?? null,
+    name: content.name ?? null,
+    mimeType: content.mimeType ?? null,
+    size: typeof content.size === "number" ? content.size : null,
+  };
+  if (content.type === "voice" && typeof content.duration === "number") {
+    meta.duration = content.duration;
+  }
+
+  // Read the bytes eagerly and base64-inline them as `data` so the Python
+  // adapter can cache the real file (the agent then sees images and can run
+  // STT on voice notes). Spectrum content objects may not outlive this stream
+  // iteration, so a lazy/on-demand fetch isn't safe. Over-cap content (when
+  // size is known up front) is forwarded as metadata only and the adapter falls
+  // back to a text marker. A read failure must never break the inbound loop.
+  const label = `${content.type} ${meta.name ?? meta.id ?? "(unnamed)"}`;
+  if (meta.size !== null && meta.size > MAX_INLINE_ATTACHMENT_BYTES) {
+    console.error(
+      `photon-sidecar: ${label} (${meta.size} bytes) ` +
+        `exceeds inline cap ${MAX_INLINE_ATTACHMENT_BYTES}; forwarding metadata only`
+    );
+    return meta;
+  }
+  if (typeof content.read === "function") {
+    try {
+      const buf = await content.read();
+      // Guard the case where size was unknown but the bytes turn out to be
+      // over the cap.
+      if (buf && buf.length > MAX_INLINE_ATTACHMENT_BYTES) {
+        console.error(
+          `photon-sidecar: ${label} (${buf.length} bytes) ` +
+            `exceeds inline cap after read; forwarding metadata only`
+        );
+        return meta;
+      }
+      meta.data = Buffer.from(buf).toString("base64");
+      meta.encoding = "base64";
+    } catch (e) {
+      console.error(
+        `photon-sidecar: failed to read ${content.type} bytes ` +
+          "(forwarding metadata only): " +
+          (e && e.stack ? e.stack : String(e))
+      );
+    }
+  }
+  return meta;
+}
+
+async function normalizeContent(content) {
+  if (!content || typeof content !== "object") {
+    return { type: "unknown" };
+  }
+  if (content.type === "text") {
+    return { type: "text", text: content.text || "" };
+  }
+  if (content.type === "attachment" || content.type === "voice") {
+    return await normalizeBinaryContent(content);
+  }
+  if (content.type === "reaction") {
+    return {
+      type: "reaction",
+      emoji: content.emoji || "",
+      targetMessageId: content.target?.id ?? null,
+      // Lets Python gate "is this a reaction to one of MY messages" without
+      // tracking every outbound id. May be null if the provider doesn't
+      // hydrate the target — Python falls back to its own sent-id cache.
+      targetDirection: content.target?.direction ?? null,
+    };
+  }
+  return { type: content.type || "unknown" };
+}
+
+async function normalizeEvent(space, message) {
+  try {
+    const msgSpace = message.space || {};
+    const ts = message.timestamp;
+    return {
+      messageId: message.id ?? null,
+      platform: message.platform || space.__platform || "iMessage",
+      space: {
+        id: space.id ?? msgSpace.id ?? null,
+        // iMessage spaces carry `type` ("dm"|"group") and `phone` directly.
+        type: space.type ?? msgSpace.type ?? "dm",
+        phone: space.phone ?? msgSpace.phone ?? null,
+      },
+      sender: { id: message.sender ? message.sender.id : null },
+      content: await normalizeContent(message.content),
+      timestamp:
+        ts instanceof Date ? ts.toISOString() : ts ? String(ts) : null,
+    };
+  } catch (e) {
+    console.error(
+      "photon-sidecar: failed to normalize inbound message: " + String(e)
+    );
+    return null;
+  }
+}
+
+// spectrum-ts handles in-session gRPC reconnects internally, but if the async
+// iterator itself throws or ends, this consumer would stop forever. Wrap it in
+// a re-subscribe loop with capped exponential backoff + jitter so inbound
+// always recovers (the adapter dedupes any catch-up replay).
+(async () => {
+  let backoff = 1000;
+  for (;;) {
+    try {
+      for await (const [space, message] of app.messages) {
+        backoff = 1000; // healthy traffic — reset
+        // Only forward inbound messages (ignore our own outbound echoes).
+        if (message && message.direction && message.direction !== "inbound") {
+          continue;
+        }
+        rememberInboundSpace(space, message);
+        rememberKnownMessage(message);
+        const event = await normalizeEvent(space, message);
+        if (!event) continue;
+        await deliver(JSON.stringify(event));
+      }
+      console.error("photon-sidecar: inbound stream ended — re-subscribing");
+    } catch (e) {
+      console.error(
+        "photon-sidecar: inbound stream errored — restarting: " +
+          (e && e.message ? e.message : String(e))
+      );
+    }
+    await new Promise((r) =>
+      setTimeout(r, backoff + Math.random() * backoff * 0.2)
+    );
+    backoff = Math.min(backoff * 2, 30000);
+  }
+})();
+
+// ---------------------------------------------------------------------------
+// HTTP control + inbound server (loopback only).
+
+// Control-message bodies are tiny; cap the body so a compromised local peer
+// can't OOM the sidecar by streaming an unbounded request (defence-in-depth on
+// the loopback channel).
+const MAX_BODY_BYTES = 2 * 1024 * 1024; // 2 MiB
+async function readBody(req) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > MAX_BODY_BYTES) {
+      req.destroy();
+      throw new Error("request body too large");
+    }
+    chunks.push(chunk);
+  }
+  const raw = Buffer.concat(chunks).toString("utf-8");
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    throw new Error("invalid JSON body");
+  }
+}
+
+function unauthorized(res) {
+  res.statusCode = 401;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify({ ok: false, error: "unauthorized" }));
+}
+
+function badRequest(res, msg) {
+  res.statusCode = 400;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify({ ok: false, error: msg }));
+}
+
+function serverError(res) {
+  res.statusCode = 500;
+  res.setHeader("Content-Type", "application/json");
+  // Don't leak stack traces or raw exception text to the caller — even
+  // though we listen on loopback, the supervisor logs the real error
+  // and the client only needs a generic failure signal.
+  res.end(JSON.stringify({ ok: false, error: "internal sidecar error" }));
+}
+
+function ok(res, data) {
+  res.statusCode = 200;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify({ ok: true, ...data }));
+}
+
+function handleInbound(req, res) {
+  res.statusCode = 200;
+  res.setHeader("Content-Type", "application/x-ndjson");
+  res.setHeader("Cache-Control", "no-store");
+  res.setHeader("Connection", "keep-alive");
+  // One consumer at a time — a fresh connection (e.g. after a reconnect)
+  // supersedes the previous one.
+  if (consumerRes && consumerRes !== res) {
+    try {
+      consumerRes.end();
+    } catch {
+      /* ignore */
+    }
+  }
+  setConsumer(res);
+  // Heartbeat keeps the socket warm through idle periods and lets the Python
+  // side detect a dead pipe promptly.
+  const heartbeat = setInterval(() => {
+    try {
+      res.write("\n");
+    } catch {
+      /* ignore */
+    }
+  }, 25000);
+  const cleanup = () => {
+    clearInterval(heartbeat);
+    clearConsumer(res);
+  };
+  req.on("close", cleanup);
+  req.on("aborted", cleanup);
+  res.on("error", cleanup);
+}
+
+async function resolveSpace(spaceId) {
+  const cached = knownSpaces.get(spaceId);
+  if (cached) return cached;
+
+  const im = imessage(app);
+  const phoneTarget = phoneTargetFromSpaceId(spaceId);
+  let space = null;
+
+  // A bare E.164 phone number addresses a DM, so callers can pass just
+  // "+1..." (e.g. PHOTON_HOME_CHANNEL for cron delivery) instead of an opaque
+  // inbound space id. Photon also represents DM chat ids as `any;-;+1...`;
+  // normalize those through the same path. `space.create` accepts the raw
+  // phone string directly.
+  if (phoneTarget) {
+    try {
+      space = await im.space.create(phoneTarget);
+    } catch (e) {
+      console.error(
+        "photon-sidecar: phone->DM space.create failed: " +
+          (e && e.stack ? e.stack : String(e))
+      );
+    }
+  }
+  // Anything else — typically an opaque group GUID — is rehydrated from the
+  // persisted id via `space.get`, so group spaces stay reachable after a
+  // sidecar restart even before any fresh inbound message in that group.
+  if (!space) {
+    try {
+      space = await im.space.get(spaceId);
+    } catch (e) {
+      console.error(
+        "photon-sidecar: space.get failed: " +
+          (e && e.stack ? e.stack : String(e))
+      );
+    }
+  }
+  if (!space) throw new Error(`unable to resolve space id ${spaceId}`);
+
+  rememberKnownSpace(spaceId, space);
+  if (phoneTarget) rememberKnownSpace(phoneTarget, space);
+  rememberKnownSpace(space?.id, space);
+  return space;
+}
+
+// Constant-time token comparison — don't leak the token via `!==` timing.
+const _tokenBuf = Buffer.from(sharedToken);
+function tokenOk(header) {
+  if (typeof header !== "string") return false;
+  const h = Buffer.from(header);
+  return h.length === _tokenBuf.length && crypto.timingSafeEqual(h, _tokenBuf);
+}
+
+const server = http.createServer(async (req, res) => {
+  if (!tokenOk(req.headers["x-hermes-sidecar-token"])) {
+    return unauthorized(res);
+  }
+  // Long-lived inbound NDJSON stream.
+  if (req.method === "GET" && req.url === "/inbound") {
+    return handleInbound(req, res);
+  }
+  if (req.method !== "POST") {
+    res.statusCode = 405;
+    return res.end();
+  }
+  try {
+    if (req.url === "/healthz") {
+      return ok(res, {});
+    }
+    if (req.url === "/shutdown") {
+      ok(res, {});
+      setTimeout(() => process.kill(process.pid, "SIGTERM"), 50);
+      return;
+    }
+    const body = await readBody(req);
+    if (req.url === "/send") {
+      const { spaceId, text, format = "text" } = body || {};
+      if (!spaceId || typeof text !== "string") {
+        return badRequest(res, "spaceId and text are required");
+      }
+      if (format !== "text" && format !== "markdown") {
+        return badRequest(res, "format must be text or markdown");
+      }
+      const space = await resolveSpace(spaceId);
+      // iMessage renders markdown natively; spectrum-ts degrades it to
+      // readable plain text on platforms that don't.
+      const builder =
+        format === "markdown" ? spectrumMarkdown(text) : spectrumText(text);
+      const result = await space.send(builder);
+      return ok(res, { messageId: result?.id || null });
+    }
+    if (req.url === "/send-attachment") {
+      const { spaceId, path, name, mimeType, caption, kind } =
+        body || {};
+      if (!spaceId || typeof path !== "string" || !path) {
+        return badRequest(res, "spaceId and path are required");
+      }
+      const space = await resolveSpace(spaceId);
+
+      // spectrum-ts infers name + MIME from the file extension; pass
+      // overrides only when Hermes supplied them so a known-good
+      // inference isn't clobbered with an empty string.
+      const opts = {};
+      if (name) opts.name = name;
+      if (mimeType) opts.mimeType = mimeType;
+      const builder =
+        kind === "voice"
+          ? voice(path, Object.keys(opts).length ? opts : undefined)
+          : attachment(path, Object.keys(opts).length ? opts : undefined);
+
+      const result = await space.send(builder);
+
+      // iMessage delivers the caption as a separate bubble; send it
+      // after the media so the attachment renders first.
+      if (caption && typeof caption === "string") {
+        try {
+          await space.send(spectrumText(caption));
+        } catch (e) {
+          console.error(
+            "photon-sidecar: attachment sent but caption failed: " +
+              (e && e.stack ? e.stack : String(e))
+          );
+        }
+      }
+      return ok(res, { messageId: result?.id || null });
+    }
+    if (req.url === "/react") {
+      const { spaceId, messageId, emoji } = body || {};
+      if (!spaceId || !messageId || typeof emoji !== "string" || !emoji) {
+        return badRequest(res, "spaceId, messageId and emoji are required");
+      }
+      const space = await resolveSpace(spaceId);
+      const target =
+        knownMessages.get(messageId) ?? (await space.getMessage(messageId));
+      if (!target) {
+        return badRequest(res, "message not found");
+      }
+      const handle = await target.react(emoji);
+      if (!handle) {
+        return badRequest(res, "reactions not supported on this platform");
+      }
+      lruSet(
+        reactionHandles,
+        `${spaceId}\u0000${messageId}`,
+        { emoji, handle },
+        MAX_REACTION_HANDLES
+      );
+      return ok(res, { reactionId: handle.id ?? null });
+    }
+    if (req.url === "/unreact") {
+      const { spaceId, messageId, reactionId } = body || {};
+      if (!spaceId || !messageId) {
+        return badRequest(res, "spaceId and messageId are required");
+      }
+      const key = `${spaceId}\u0000${messageId}`;
+      const slot = reactionHandles.get(key);
+      if (slot) {
+        await slot.handle.unsend();
+        reactionHandles.delete(key);
+        return ok(res, {});
+      }
+      // Restart-recovery: the live handle is gone, so try rehydrating the
+      // reaction message by id and retracting it. Only outbound messages can
+      // be unsent — if the provider rehydrates it as inbound (or not at all)
+      // this throws, and that's an expected soft failure, not a sidecar bug:
+      // a stale tapback self-heals when the next /react replaces it.
+      if (reactionId) {
+        try {
+          const space = await resolveSpace(spaceId);
+          const msg = await space.getMessage(reactionId);
+          if (msg) {
+            await space.unsend(msg);
+            return ok(res, {});
+          }
+        } catch (e) {
+          console.error(
+            "photon-sidecar: best-effort unreact failed: " +
+              (e && e.message ? e.message : String(e))
+          );
+        }
+        return badRequest(res, "reaction not removable");
+      }
+      return badRequest(res, "no tracked reaction for message");
+    }
+    if (req.url === "/typing") {
+      const { spaceId, state = "start" } = body || {};
+      if (!spaceId) return badRequest(res, "spaceId is required");
+      if (state !== "start" && state !== "stop") {
+        return badRequest(res, "state must be start or stop");
+      }
+      const space = await resolveSpace(spaceId);
+      await space.send(spectrumTyping(state));
+      return ok(res, {});
+    }
+    res.statusCode = 404;
+    res.setHeader("Content-Type", "application/json");
+    return res.end(JSON.stringify({ ok: false, error: "not found" }));
+  } catch (e) {
+    console.error(
+      "photon-sidecar: handler error: " +
+        (e && e.stack ? e.stack : String(e))
+    );
+    // serverError() intentionally returns a generic message — see its
+    // body for the rationale.
+    return serverError(res);
+  }
+});
+
+server.listen(port, bind, () => {
+  console.error(`photon-sidecar: listening on ${bind}:${port}`);
+});
+
+let stopping = false;
+async function shutdown(signal) {
+  // Re-entry guard: stdin EOF, a signal and /shutdown can all fire together
+  // during one teardown.
+  if (stopping) return;
+  stopping = true;
+  console.error(`photon-sidecar: received ${signal}, stopping...`);
+  try {
+    await Promise.race([
+      app.stop(),
+      new Promise((resolve) => setTimeout(resolve, 3000)),
+    ]);
+  } catch (e) {
+    console.error("photon-sidecar: app.stop() failed: " + String(e));
+  }
+  server.close(() => process.exit(0));
+  setTimeout(() => process.exit(1), 500).unref();
+}
+
+process.on("SIGINT", () => shutdown("SIGINT"));
+process.on("SIGTERM", () => shutdown("SIGTERM"));
+
+// Lifetime binding to the parent. The adapter spawns us with stdin as a pipe
+// it holds open; EOF means the gateway process is gone — including hard
+// deaths (crash, SIGKILL) where no signal and no /shutdown ever reaches us.
+// Without this, an orphaned sidecar squats the port and keeps consuming the
+// inbound gRPC stream, and every replacement spawn dies on EADDRINUSE.
+// Opt-in via env so manual `node index.mjs` runs aren't affected.
+if (process.env.PHOTON_SIDECAR_WATCH_STDIN === "1") {
+  process.stdin.resume();
+  process.stdin.on("end", () => shutdown("stdin EOF (parent exited)"));
+  process.stdin.on("error", () => shutdown("stdin error (parent exited)"));
+}
+
+// Don't let a stray promise rejection take the process down silently — handlers
+// catch their own errors, so log and keep serving (Python supervises restart on
+// a real fatal exit).
+process.on("unhandledRejection", (reason) => {
+  console.error(
+    "photon-sidecar: unhandledRejection: " +
+      (reason && reason.stack ? reason.stack : String(reason))
+  );
+});

plugins/platforms/photon/sidecar/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@hermes-agent/photon-sidecar",
+  "private": true,
+  "version": "0.3.0",
+  "description": "Spectrum-ts bridge for the Hermes Agent Photon platform plugin.",
+  "type": "module",
+  "main": "index.mjs",
+  "scripts": {
+    "start": "node index.mjs"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "dependencies": {
+    "spectrum-ts": "3.1.0"
+  },
+  "overrides": {
+    "protobufjs": "8.6.1",
+    "@opentelemetry/otlp-transformer": "0.218.0",
+    "@opentelemetry/otlp-exporter-base": "0.218.0",
+    "@opentelemetry/exporter-trace-otlp-http": "0.218.0",
+    "@opentelemetry/exporter-logs-otlp-http": "0.218.0"
+  }
+}

plugins/platforms/simplex/__init__.py

@@ -0,0 +1,3 @@
+from .adapter import register
+
+__all__ = ["register"]

plugins/platforms/simplex/plugin.yaml

@@ -0,0 +1,56 @@
+name: simplex-platform
+label: SimpleX Chat
+kind: platform
+version: 1.1.0
+description: >
+  SimpleX Chat gateway adapter for Hermes Agent.
+  Connects to a local simplex-chat daemon via WebSocket and relays
+  messages between SimpleX contacts/groups and the Hermes agent.
+  SimpleX is decentralised and assigns no persistent user IDs —
+  every contact is an opaque internal ID generated at connection
+  time, making it one of the most private messengers available.
+author: Mibayy, jooray
+# ``requires_env`` and ``optional_env`` entries are surfaced in the
+# ``hermes config`` UI via the platform-plugin env var injector in
+# ``hermes_cli/config.py``.
+requires_env:
+  - name: SIMPLEX_WS_URL
+    description: "WebSocket URL of the simplex-chat daemon (e.g. ws://127.0.0.1:5225)"
+    prompt: "SimpleX daemon WebSocket URL"
+    password: false
+optional_env:
+  - name: SIMPLEX_ALLOWED_USERS
+    description: "Comma-separated SimpleX contact IDs allowed to talk to the bot"
+    prompt: "Allowed contact IDs (comma-separated)"
+    password: false
+  - name: SIMPLEX_ALLOW_ALL_USERS
+    description: "Allow any contact to talk to the bot (dev only — disables allowlist)"
+    prompt: "Allow all contacts? (true/false)"
+    password: false
+  - name: SIMPLEX_AUTO_ACCEPT
+    description: "Auto-accept incoming contact requests (default: true)"
+    prompt: "Auto-accept contact requests? (true/false)"
+    password: false
+  - name: SIMPLEX_GROUP_ALLOWED
+    description: >-
+      Comma-separated SimpleX group IDs the bot should participate in, or
+      '*' to allow any group. Omit to ignore group messages entirely
+      (safer default — a bot in a group otherwise processes every
+      member's traffic).
+    prompt: "Allowed group IDs (comma-separated, or '*' for any)"
+    password: false
+  - name: SIMPLEX_HOME_CHANNEL
+    description: "Default contact/group ID for cron / notification delivery"
+    prompt: "Home channel contact/group ID (or empty)"
+    password: false
+  - name: SIMPLEX_HOME_CHANNEL_NAME
+    description: "Human label for the home channel (defaults to the ID)"
+    prompt: "Home channel display name (or empty)"
+    password: false
+  - name: HERMES_SIMPLEX_TEXT_BATCH_DELAY
+    description: >-
+      Quiet-period seconds (default: 0.8) used to concatenate rapid-fire
+      inbound text messages into a single MessageEvent — same pattern as
+      Telegram's text batching.
+    prompt: "Text batch flush delay in seconds (default 0.8)"
+    password: false

plugins/platforms/teams/__init__.py

@@ -0,0 +1,3 @@
+from .adapter import register
+
+__all__ = ["register"]

plugins/platforms/teams/plugin.yaml

@@ -0,0 +1,48 @@
+name: teams-platform
+label: Microsoft Teams
+kind: platform
+version: 1.0.0
+description: >
+  Microsoft Teams gateway adapter for Hermes Agent.
+  Connects to Microsoft Teams via the Bot Framework and relays messages
+  between Teams chats (personal DMs, group chats, channel posts) and
+  the Hermes agent. Supports Adaptive Card approval prompts.
+author: Aamir Jawaid
+# ``requires_env`` entries are surfaced in ``hermes config`` UI via the
+# platform-plugin env var injector in ``hermes_cli/config.py``.
+requires_env:
+  - name: TEAMS_CLIENT_ID
+    description: "Azure AD application (Bot Framework) client ID"
+    prompt: "Teams / Azure AD client ID"
+    url: "https://portal.azure.com/"
+    password: false
+  - name: TEAMS_CLIENT_SECRET
+    description: "Azure AD application client secret"
+    prompt: "Teams / Azure AD client secret"
+    url: "https://portal.azure.com/"
+    password: true
+  - name: TEAMS_TENANT_ID
+    description: "Azure AD tenant ID hosting the bot application"
+    prompt: "Teams / Azure AD tenant ID"
+    password: false
+optional_env:
+  - name: TEAMS_PORT
+    description: "Webhook listen port (Bot Framework default: 3978)"
+    prompt: "Webhook port"
+    password: false
+  - name: TEAMS_ALLOWED_USERS
+    description: "Comma-separated Teams user IDs / UPNs allowed to talk to the bot"
+    prompt: "Allowed users (comma-separated)"
+    password: false
+  - name: TEAMS_ALLOW_ALL_USERS
+    description: "Allow any Teams user to trigger the bot (dev only)"
+    prompt: "Allow all users? (true/false)"
+    password: false
+  - name: TEAMS_HOME_CHANNEL
+    description: "Default chat/channel ID for cron / notification delivery"
+    prompt: "Home channel (or empty)"
+    password: false
+  - name: TEAMS_HOME_CHANNEL_NAME
+    description: "Display name for the Teams home channel"
+    prompt: "Home channel display name"
+    password: false