hermes-chatto-plugin/platform_config.py

"""
Chatto Platform Config


"""

import os
import re

# Put the vendored dependencies for THIS platform on sys.path before importing
# anything from chattolib. Imported relatively as part of the plugin package and
# absolutely when this module is loaded standalone (e.g. by the tests).
try:
    from .vendor_path import setup_vendor_path
except ImportError:  # pragma: no cover - depends on how the module is loaded
    from vendor_path import setup_vendor_path

setup_vendor_path()

import logging
from collections.abc import Mapping
from typing import Any, ClassVar, Generic, TypeVar

import utils

# Absolute import — the vendor dir is on sys.path (see above) and chattolib's
# own modules import each other absolutely ("from chattolib.x import y").
# Importing it relatively as well would load a *second* copy of every module
# under a different name, so isinstance() checks across the two would fail.
from chattolib import ChattoClient
from gateway.config import PlatformConfig

logger = logging.getLogger(__name__)

# --------------------------------------------------------------------------- #
# Constants
# --------------------------------------------------------------------------- #


class ChattoConstants:
    """
    Chatto Platform Constants
    """

    def __init__(self):
        pass

    PLATFORM_NAME: str = "chatto-platform"
    PLATFORM_LABEL: str = "Chatto"

    INSTALL_HINT = "Requires a Chatto server. See https://docs.chatto.run"

    # NOTE: env var names live on the ConfigFields below (ConfigField.env_name),
    # so there is exactly one source of truth for them.

    MAX_MESSAGE_LENGTH = 10000
    # Outgoing text is split below this rather than at MAX_MESSAGE_LENGTH, so
    # a full chunk plus the gateway's multi-chunk "(1/2)" label stays under
    # the server limit.
    SPLIT_THRESHOLD = 9900
    SEEN_CAP = 500

    # Members fetched per roster delivery (the context block handed to the
    # agent alongside every channel turn). The roster rides on each message,
    # so the cap keeps the prompt block small; larger rooms get an "and N
    # more" note instead.
    ROSTER_MEMBER_LIMIT = 20

    # Thread messages handed to the agent on the FIRST turn of a thread (see
    # ChattoAdapter._thread_context_for). A thread session starts empty, so
    # without this block a reply that roots a thread is answered without the
    # thread it replies to. Both caps bound the one-shot block: the message
    # count bounds the fetch, the character count bounds what reaches the
    # prompt — the oldest messages are dropped first when the second bites.
    THREAD_CONTEXT_MESSAGE_LIMIT = 20
    THREAD_CONTEXT_CHAR_LIMIT = 2000

    # WebSocket reconnect backoff (the realtime transport itself lives in
    # chattolib.realtime, which owns protocol-level constants).
    WS_RECONNECT_INITIAL_BACKOFF = 1.0
    WS_RECONNECT_MAX_BACKOFF = 30.0

    # A candidate @-handle, not a confirmed one — every match is resolved
    # against the member directory before it counts. Pattern mirrors the Chatto
    # web frontend's mention extraction: dots are internal separators only, so
    # a sentence-ending "frag @bob." yields the handle "bob", and a leading
    # hyphen ("per @-mention") yields nothing to look up. The lookbehind keeps
    # the domain half of an e-mail address from becoming a candidate.
    MENTION_RE = re.compile(
        r"(?<![\w.])@([A-Za-z0-9_](?:[A-Za-z0-9_-]|\.(?=[A-Za-z0-9_-]))*)"
    )

    # Handles that address the room rather than a person — the bot is one of
    # the addressees, so these do not mean "this is for someone else".
    # Chatto defines exactly these two virtual handles (FDR-006); anything
    # else must resolve to a real user in the directory.
    BROADCAST_MENTIONS = frozenset({"all", "here"})

    # Presence is a TTL the server lets lapse — chattolib refuses to set OFFLINE
    # at all ("stop refreshing to go offline"), so staying online means
    # re-announcing ONLINE on this interval for as long as we are connected.
    PRESENCE_REFRESH_INTERVAL = 60.0

    # HTTP timeout used for outbound URL fetches
    HTTP_TIMEOUT = 30

    # Emoji shortcode mapping (Chatto uses shortcode names, not unicode emoji)
    EMOJI_TO_SHORTCODE: ClassVar[dict[str, str]] = {
        "👍": "thumbsup",
        "👎": "thumbsdown",
        "❤️": "heart",
        "❤": "heart",
        "✅": "white_check_mark",
        "❌": "x",
        "🚫": "no_entry_sign",
        "⛔": "no_entry",
        "👀": "eyes",
        "🫥": "dotted_line_face",
        "🎉": "tada",
        "😂": "joy",
        "🚀": "rocket",
        "🔥": "fire",
        "💯": "100",
        "🤔": "thinking_face",
        "👏": "clap",
        "🙏": "pray",
        "😅": "sweat_smile",
        "😴": "sleeping",
        "⏳": "hourglass",
        "💭": "thought_balloon",
        "👓": "glasses",
        "👁️‍🗨️": "eye_in_speech_bubble",
        "💬": "speech_balloon",
        "🗨️": "left_speech_bubble",
        "🗯️": "right_anger_bubble",
        "🦾": "mechanical_arm",
        "🦿": "mechanical_leg",
    }

    # Chunk size for asset uploads (256 KB)
    UPLOAD_CHUNK_SIZE = 256 * 1024


def _parse_str_opt(raw: str | bool | None, default: str | None = None) -> str | None:
    """Parse one raw value into a plain string, or None when there is none.

    Each kind is parsed by a ``_parse_*`` function; the ``_get_env_or_extra_*``
    wrappers below decide *where* a value comes from, these decide what it
    means — so a value read from one source cannot parse differently than the
    same value read from another.
    """
    if raw is not None:
        if isinstance(raw, str):
            return raw.strip()
        elif isinstance(raw, bool):
            return str(raw)
        else:
            logger.error(
                "raw value: %s is supposed to be str, but %s was found.",
                raw,
                str(type(raw)),
            )

    if default is not None:
        logger.debug("Chatto: Defaulting to '%s'", default)
        return default.strip()
    return None


def _parse_str(raw: str | bool | None, default: str | None = None) -> str:
    """Parse one raw value into a plain string; an absent value becomes ""."""
    value = _parse_str_opt(raw, default)
    return value if value else ""


def _parse_truthy(raw: str | bool | None, default: bool = False) -> bool:
    """Parse one raw value into a boolean, ``default`` standing in for absent."""
    return utils.is_truthy_value(_parse_str(raw, str(default)), default)


def _split_str_to_list(mystring: str) -> list[str]:
    """Split a comma-separated string, trimming whitespace and dropping empties."""
    return [part.strip() for part in mystring.split(",") if part.strip()]


def _parse_list(raw: list[str] | str | None) -> list[str]:
    """Parse one raw value into a list, from a list or a comma-separated string."""
    if isinstance(raw, list):
        return [str(c).strip() for c in raw if str(c).strip()]
    if isinstance(raw, str):
        return _split_str_to_list(raw)
    return []


def _parse_int(raw: Any, env_name: str, default: int) -> int:
    """Parse one raw value into an integer.

    Unparseable values fall back to the default with a warning rather than
    raising — a typo in an env var must not keep the plugin from starting.
    """
    if isinstance(raw, bool):  # a YAML true/false is not a number
        raw = None
    elif isinstance(raw, (int, float)):
        return int(raw)
    elif isinstance(raw, str) and raw.strip():
        try:
            return int(raw.strip())
        except ValueError:
            logger.warning(
                "Chatto: %s=%r is not an integer, using default %d",
                env_name,
                raw,
                default,
            )
    return default


def _get_env_or_extra_str_opt(
    env_var: str, extra_val: str | bool | None, default: str | None = None
) -> str | None:
    """Get a value from environment variable or extra config."""
    env_value = os.getenv(env_var)
    if env_value is not None:
        return _parse_str_opt(env_value)
    return _parse_str_opt(extra_val, default)


def _get_env_or_extra_str(
    env_var: str, extra_val: str | bool | None, default: str | None = None
) -> str:
    """Get a string value from environment variable or extra config."""
    my_string = _get_env_or_extra_str_opt(env_var, extra_val, default)
    if my_string:
        return my_string
    return ""


def _get_env_or_extra_truthy(
    env_var: str, extra_val: str | bool | None, default: bool = False
) -> bool:
    """Get a boolean value from environment variable or extra config."""
    env_value = os.getenv(env_var)
    if env_value is not None:
        return _parse_truthy(env_value, default)
    return _parse_truthy(extra_val, default)


def _get_env_or_extra_list(env_var: str, extra_val: list[str] | None) -> list[str]:
    """Get a list of values from environment variable or extra config."""
    env_value = os.getenv(env_var)
    if env_value is not None:
        return _parse_list(env_value)
    return _parse_list(extra_val)


def _get_env_or_extra_int(env_var: str, extra_val: Any, default: int) -> int:
    """Get an integer value from environment variable or extra config."""
    env_value = os.getenv(env_var)
    if env_value is None or not env_value.strip():
        return _parse_int(extra_val, env_var, default)
    return _parse_int(env_value, env_var, default)


T = TypeVar("T")


class ConfigValue(Generic[T]):
    """The resolved value of a single config field, bound to one configuration
    instance.

    Access the payload via ``.value``.  ``__bool__``/``__eq__`` delegate to it,
    so a forgotten ``.value`` (``if config.allow_all_users:``) still evaluates
    the actual setting instead of the always-truthy wrapper object.
    """

    __slots__ = ("env_name", "explicit", "field_name", "value")

    def __init__(
        self, value: T, field_name: str, env_name: str, explicit: bool = False
    ) -> None:
        self.value = value
        self.field_name = field_name
        self.env_name = env_name
        # explicit: True when the value came from the user (env var or extra),
        # False when it is merely the declared default. Defaults are
        # structurally indistinguishable from user input by value alone —
        # a user *may* deliberately set base_url to the default string —
        # so the origin must be carried alongside the value.
        self.explicit = explicit

    def __bool__(self) -> bool:
        return bool(self.value)

    def __eq__(self, other: object) -> bool:
        if isinstance(other, ConfigValue):
            return self.value == other.value
        return self.value == other

    def __hash__(self) -> int:
        return hash(self.value)

    def __contains__(self, item: Any) -> bool:
        return item in self.value  # type: ignore[operator]

    def __iter__(self):
        return iter(self.value)  # type: ignore[call-overload]

    def __str__(self) -> str:
        return str(self.value)

    def __repr__(self) -> str:
        return f"{self.field_name}={self.value!r}"


class ConfigField(Generic[T]):
    """Declarative descriptor for one config field.

    Declares *how* a field is read (kind, env var name, default); the resolved
    payload lives per configuration instance in ``instance._values``, never on
    the descriptor itself.  Reading a field on the class (rather than on an
    instance) yields the descriptor, so ``ChattoConfiguration.token.env_name``
    keeps working for the registration hooks.
    """

    field_name: str = ""
    env_name: str = ""

    def __init__(
        self,
        kind: str,
        *,
        default: Any = None,
        config_key: str | None = None,
        doc: str = "",
    ) -> None:
        # kind: "str" | "str_opt" | "bool" | "list"
        self.kind = kind
        self.default = default
        # config_key: the name used in config.yaml's "extra" block and (upper-cased,
        # CHATTO_-prefixed) as the env var, where it differs from the attribute name.
        self._config_key = config_key
        self.__doc__ = doc

    def __set_name__(self, owner: Any, name: str) -> None:
        self.field_name = str(name).lower().replace("chatto_", "", 1)
        self.config_key = self._config_key or self.field_name
        self.env_name = f"CHATTO_{self.config_key.upper()}"

    def __get__(self, instance: Any, owner: Any = None) -> "ConfigValue[T]":
        if instance is None:
            return self  # type: ignore[return-value]
        return instance._values[self.field_name]

    def __set__(self, instance: Any, value: Any) -> None:
        raise AttributeError(
            f"Chatto: config field '{self.field_name}' is read-only; "
            f"set '{self.field_name}.value' if you really need to override it."
        )

    def coerce(self, raw: Any) -> Any:
        """Parse one raw value the way ``kind`` implies, reading no source.

        Every path into a field's payload ends here, so a value that arrives
        from the profile-.env overlay is typed exactly like one read from the
        environment or config.yaml. It has to be: the ``.env`` spells a list as
        a comma-separated string and a bool as ``"false"``, and consumers index,
        concatenate and test truthiness on these fields — a list field holding
        a string turns ``room_id in require + optional`` into a substring test,
        and ``"false"`` is true.
        """
        if self.kind == "list":
            return _parse_list(raw)
        if self.kind == "bool":
            return _parse_truthy(raw, bool(self.default))
        if self.kind == "int":
            return _parse_int(raw, self.env_name, int(self.default))
        if self.kind == "str_opt":
            return _parse_str_opt(raw, self.default)
        return _parse_str(raw, self.default)

    def resolve(self, extra: dict[str, Any]) -> ConfigValue:
        """Read this field from the environment, then from ``extra``, then the default."""
        raw = extra.get(self.config_key)
        # "The user set it somewhere" — a blank value still counts as set here,
        # because for a bool that is the only way to tell an explicit "false"
        # from the declared default.
        raw_present = os.getenv(self.env_name) is not None or raw is not None

        if self.kind == "list":
            value: Any = _get_env_or_extra_list(self.env_name, raw)
        elif self.kind == "bool":
            value = _get_env_or_extra_truthy(self.env_name, raw, bool(self.default))
        elif self.kind == "int":
            value = _get_env_or_extra_int(self.env_name, raw, int(self.default))
        elif self.kind == "str_opt":
            value = _get_env_or_extra_str_opt(self.env_name, raw, self.default)
        else:
            value = _get_env_or_extra_str(self.env_name, raw, self.default)

        # A blank value is a placeholder, not intent: `CHATTO_TOKEN=` left
        # behind by the installer must not count as "the user set the token",
        # or the tool-layer fallback — which yields to explicit values — would
        # never reach the real secret in the profile's .env. A bool is never
        # blank, so `False` there stays explicit.
        blank = value is None or value == "" or value == []
        explicit = raw_present and not blank

        return ConfigValue(value, self.field_name, self.env_name, explicit=explicit)


class ChattoConfiguration:
    """Chatto platform configuration.

    Every field is resolved once per instance, in this order:
    environment variable → ``PlatformConfig.extra`` → declared default.
    """

    base_url = ConfigField("str", default=ChattoClient.DEFAULT_BASE_URL)
    token = ConfigField("str_opt")
    home_channel = ConfigField("str")
    allowed_users = ConfigField("list")
    # Participation in multi-person rooms is opt-in: require_mention_rooms
    # lists rooms where the bot answers only when addressed
    # (@name/@all/@here), optional_mention_rooms lists rooms where it answers
    # everything. A room in neither list stays silent — read-only, never
    # seeded into context or answered. Chatto has no group rooms like Signal:
    # every non-DM surface is a channel-kind room, so these two lists are the
    # only inbound gate; DMs always answer.
    require_mention_rooms = ConfigField("list")
    optional_mention_rooms = ConfigField("list")
    # Auto-thread: by default, Chatto creates a thread for replies to room
    # messages (not DMs, not already in a thread). This keeps conversations
    # organized in the room. Can be disabled via extra.auto_thread=false.
    auto_thread = ConfigField("bool", default=True)
    allow_all_users = ConfigField("bool", default=False)
    reactions = ConfigField("bool", default=True)
    # Inbound edits: a message_edited event re-runs the admission gates against
    # the new body. A message currently being processed is cancelled and
    # re-dispatched with the corrected text; a message that never passed the
    # gates (e.g. a forgotten @mention) gets a fresh turn; an already-answered
    # message stays answered.
    edit_dispatch = ConfigField("bool", default=True)
    # How long after posting an edit may still land, in seconds — edits to
    # hours-old messages must not resurrect old conversations. Parsed by
    # ConfigField's "int" kind; unparseable input falls back to the default.
    edit_window = ConfigField("int", default=300)

    def __init__(self, pconfig: PlatformConfig):
        """Resolve every declared ConfigField against env vars and
        ``PlatformConfig.extra`` (which Hermes pre-populates from config.yaml).
        """
        extra: dict[str, Any] = getattr(pconfig, "extra", None) or {}

        self._values: dict[str, ConfigValue] = {
            field.field_name: field.resolve(extra) for field in self.fields()
        }

        logger.debug("ChattoConfiguration: %s", self)

    @classmethod
    def fields(cls) -> list[ConfigField]:
        """All declared config fields, in declaration order."""
        return [v for v in vars(cls).values() if isinstance(v, ConfigField)]

    def overlay_profile_secrets(self, secrets: Mapping[str, str]) -> None:
        """Fill every field that is not an explicit user value from ``secrets``.

        Keyed by env var name. The plugin tools call this with the profile's own
        .env, which a cron or CLI process no longer sees through the
        environment: there, a secret would otherwise resolve to its default and
        the tool would report "token not configured" for a configured bot.

        An EXPLICIT value (env var or config.yaml extra) is the user's own
        intent and wins; a declared default or a blank placeholder yields here.

        The secret is parsed through ``ConfigField.coerce`` like any other raw
        input — a ``.env`` line is a string whatever the field means.
        """
        for config_field in self.fields():
            current = self._values.get(config_field.field_name)
            if current is not None and current.explicit:
                continue
            secret_value = secrets.get(config_field.env_name)
            if not secret_value:
                continue
            self._values[config_field.field_name] = ConfigValue(
                config_field.coerce(secret_value),
                config_field.field_name,
                config_field.env_name,
                explicit=True,
            )

    def __str__(self) -> str:
        redacted = {"token"}
        parts = [
            f"{name}={'***' if name in redacted and cv.value else cv.value!r}"
            for name, cv in self._values.items()
        ]
        return "ChattoConfiguration(" + ", ".join(parts) + ")"