yee88 0.3.0__py3-none-any.whl

yee88/telegram/topic_state.py

@@ -0,0 +1,334 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import msgspec
+
+from ..context import RunContext
+from ..logging import get_logger
+from ..model import ResumeToken
+from .engine_overrides import EngineOverrides, normalize_overrides
+from .state_store import JsonStateStore
+
+logger = get_logger(__name__)
+
+STATE_VERSION = 1
+STATE_FILENAME = "telegram_topics_state.json"
+
+
+@dataclass(frozen=True, slots=True)
+class TopicThreadSnapshot:
+    chat_id: int
+    thread_id: int
+    context: RunContext | None
+    sessions: dict[str, str]
+    topic_title: str | None
+    default_engine: str | None
+
+
+class _ContextState(msgspec.Struct, forbid_unknown_fields=False):
+    project: str | None = None
+    branch: str | None = None
+
+
+class _SessionState(msgspec.Struct, forbid_unknown_fields=False):
+    resume: str
+
+
+class _ThreadState(msgspec.Struct, forbid_unknown_fields=False):
+    context: _ContextState | None = None
+    sessions: dict[str, _SessionState] = msgspec.field(default_factory=dict)
+    topic_title: str | None = None
+    default_engine: str | None = None
+    trigger_mode: str | None = None
+    engine_overrides: dict[str, EngineOverrides] = msgspec.field(default_factory=dict)
+
+
+class _TopicState(msgspec.Struct, forbid_unknown_fields=False):
+    version: int
+    threads: dict[str, _ThreadState] = msgspec.field(default_factory=dict)
+
+
+def resolve_state_path(config_path: Path) -> Path:
+    return config_path.with_name(STATE_FILENAME)
+
+
+def _thread_key(chat_id: int, thread_id: int) -> str:
+    return f"{chat_id}:{thread_id}"
+
+
+def _normalize_text(value: str | None) -> str | None:
+    if value is None:
+        return None
+    value = value.strip()
+    return value or None
+
+
+def _normalize_trigger_mode(value: str | None) -> str | None:
+    if value is None:
+        return None
+    value = value.strip().lower()
+    if value == "mentions":
+        return "mentions"
+    if value == "all":
+        return None
+    return None
+
+
+def _normalize_engine_id(value: str | None) -> str | None:
+    if value is None:
+        return None
+    value = value.strip().lower()
+    return value or None
+
+
+def _context_from_state(state: _ContextState | None) -> RunContext | None:
+    if state is None:
+        return None
+    project = _normalize_text(state.project)
+    branch = _normalize_text(state.branch)
+    if project is None and branch is None:
+        return None
+    return RunContext(project=project, branch=branch)
+
+
+def _context_to_state(context: RunContext | None) -> _ContextState | None:
+    if context is None:
+        return None
+    project = _normalize_text(context.project)
+    branch = _normalize_text(context.branch)
+    if project is None and branch is None:
+        return None
+    return _ContextState(project=project, branch=branch)
+
+
+def _new_state() -> _TopicState:
+    return _TopicState(version=STATE_VERSION, threads={})
+
+
+class TopicStateStore(JsonStateStore[_TopicState]):
+    def __init__(self, path: Path) -> None:
+        super().__init__(
+            path,
+            version=STATE_VERSION,
+            state_type=_TopicState,
+            state_factory=_new_state,
+            log_prefix="telegram.topic_state",
+            logger=logger,
+        )
+
+    async def get_thread(
+        self, chat_id: int, thread_id: int
+    ) -> TopicThreadSnapshot | None:
+        async with self._lock:
+            self._reload_locked_if_needed()
+            thread = self._get_thread_locked(chat_id, thread_id)
+            if thread is None:
+                return None
+            return self._snapshot_locked(thread, chat_id, thread_id)
+
+    async def get_context(self, chat_id: int, thread_id: int) -> RunContext | None:
+        async with self._lock:
+            self._reload_locked_if_needed()
+            thread = self._get_thread_locked(chat_id, thread_id)
+            if thread is None:
+                return None
+            return _context_from_state(thread.context)
+
+    async def set_context(
+        self,
+        chat_id: int,
+        thread_id: int,
+        context: RunContext,
+        *,
+        topic_title: str | None = None,
+    ) -> None:
+        async with self._lock:
+            self._reload_locked_if_needed()
+            thread = self._ensure_thread_locked(chat_id, thread_id)
+            thread.context = _context_to_state(context)
+            if topic_title is not None:
+                thread.topic_title = topic_title
+            self._save_locked()
+
+    async def clear_context(self, chat_id: int, thread_id: int) -> None:
+        async with self._lock:
+            self._reload_locked_if_needed()
+            thread = self._get_thread_locked(chat_id, thread_id)
+            if thread is None:
+                return
+            thread.context = None
+            self._save_locked()
+
+    async def get_session_resume(
+        self, chat_id: int, thread_id: int, engine: str
+    ) -> ResumeToken | None:
+        async with self._lock:
+            self._reload_locked_if_needed()
+            thread = self._get_thread_locked(chat_id, thread_id)
+            if thread is None:
+                return None
+            entry = thread.sessions.get(engine)
+            if entry is None or not entry.resume:
+                return None
+            return ResumeToken(engine=engine, value=entry.resume)
+
+    async def get_default_engine(self, chat_id: int, thread_id: int) -> str | None:
+        async with self._lock:
+            self._reload_locked_if_needed()
+            thread = self._get_thread_locked(chat_id, thread_id)
+            if thread is None:
+                return None
+            return _normalize_text(thread.default_engine)
+
+    async def get_trigger_mode(self, chat_id: int, thread_id: int) -> str | None:
+        async with self._lock:
+            self._reload_locked_if_needed()
+            thread = self._get_thread_locked(chat_id, thread_id)
+            if thread is None:
+                return None
+            return _normalize_trigger_mode(thread.trigger_mode)
+
+    async def get_engine_override(
+        self, chat_id: int, thread_id: int, engine: str
+    ) -> EngineOverrides | None:
+        engine_key = _normalize_engine_id(engine)
+        if engine_key is None:
+            return None
+        async with self._lock:
+            self._reload_locked_if_needed()
+            thread = self._get_thread_locked(chat_id, thread_id)
+            if thread is None:
+                return None
+            override = thread.engine_overrides.get(engine_key)
+            return normalize_overrides(override)
+
+    async def set_default_engine(
+        self, chat_id: int, thread_id: int, engine: str | None
+    ) -> None:
+        normalized = _normalize_text(engine)
+        async with self._lock:
+            self._reload_locked_if_needed()
+            thread = self._ensure_thread_locked(chat_id, thread_id)
+            thread.default_engine = normalized
+            self._save_locked()
+
+    async def clear_default_engine(self, chat_id: int, thread_id: int) -> None:
+        await self.set_default_engine(chat_id, thread_id, None)
+
+    async def set_trigger_mode(
+        self, chat_id: int, thread_id: int, mode: str | None
+    ) -> None:
+        normalized = _normalize_trigger_mode(mode)
+        async with self._lock:
+            self._reload_locked_if_needed()
+            thread = self._ensure_thread_locked(chat_id, thread_id)
+            thread.trigger_mode = normalized
+            self._save_locked()
+
+    async def clear_trigger_mode(self, chat_id: int, thread_id: int) -> None:
+        await self.set_trigger_mode(chat_id, thread_id, None)
+
+    async def set_engine_override(
+        self,
+        chat_id: int,
+        thread_id: int,
+        engine: str,
+        override: EngineOverrides | None,
+    ) -> None:
+        engine_key = _normalize_engine_id(engine)
+        if engine_key is None:
+            return
+        normalized = normalize_overrides(override)
+        async with self._lock:
+            self._reload_locked_if_needed()
+            thread = self._ensure_thread_locked(chat_id, thread_id)
+            if normalized is None:
+                thread.engine_overrides.pop(engine_key, None)
+            else:
+                thread.engine_overrides[engine_key] = normalized
+            self._save_locked()
+
+    async def clear_engine_override(
+        self, chat_id: int, thread_id: int, engine: str
+    ) -> None:
+        await self.set_engine_override(chat_id, thread_id, engine, None)
+
+    async def set_session_resume(
+        self, chat_id: int, thread_id: int, token: ResumeToken
+    ) -> None:
+        async with self._lock:
+            self._reload_locked_if_needed()
+            thread = self._ensure_thread_locked(chat_id, thread_id)
+            thread.sessions[token.engine] = _SessionState(resume=token.value)
+            self._save_locked()
+
+    async def clear_sessions(self, chat_id: int, thread_id: int) -> None:
+        async with self._lock:
+            self._reload_locked_if_needed()
+            thread = self._get_thread_locked(chat_id, thread_id)
+            if thread is None:
+                return
+            thread.sessions = {}
+            self._save_locked()
+
+    async def delete_thread(self, chat_id: int, thread_id: int) -> None:
+        async with self._lock:
+            self._reload_locked_if_needed()
+            key = _thread_key(chat_id, thread_id)
+            if key not in self._state.threads:
+                return
+            self._state.threads.pop(key, None)
+            self._save_locked()
+
+    async def find_thread_for_context(
+        self, chat_id: int, context: RunContext
+    ) -> int | None:
+        async with self._lock:
+            self._reload_locked_if_needed()
+            target_project = _normalize_text(context.project)
+            target_branch = _normalize_text(context.branch)
+            for raw_key, thread in self._state.threads.items():
+                if not raw_key.startswith(f"{chat_id}:"):
+                    continue
+                parsed = _context_from_state(thread.context)
+                if parsed is None:
+                    continue
+                if parsed.project != target_project or parsed.branch != target_branch:
+                    continue
+                try:
+                    _, thread_str = raw_key.split(":", 1)
+                    return int(thread_str)
+                except ValueError:
+                    continue
+            return None
+
+    def _snapshot_locked(
+        self, thread: _ThreadState, chat_id: int, thread_id: int
+    ) -> TopicThreadSnapshot:
+        sessions = {
+            engine: entry.resume
+            for engine, entry in thread.sessions.items()
+            if entry.resume
+        }
+        return TopicThreadSnapshot(
+            chat_id=chat_id,
+            thread_id=thread_id,
+            context=_context_from_state(thread.context),
+            sessions=sessions,
+            topic_title=thread.topic_title,
+            default_engine=_normalize_text(thread.default_engine),
+        )
+
+    def _get_thread_locked(self, chat_id: int, thread_id: int) -> _ThreadState | None:
+        return self._state.threads.get(_thread_key(chat_id, thread_id))
+
+    def _ensure_thread_locked(self, chat_id: int, thread_id: int) -> _ThreadState:
+        key = _thread_key(chat_id, thread_id)
+        entry = self._state.threads.get(key)
+        if entry is not None:
+            return entry
+        entry = _ThreadState()
+        self._state.threads[key] = entry
+        return entry

yee88/telegram/topics.py

@@ -0,0 +1,256 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from ..config import ConfigError
+from ..context import RunContext
+from ..settings import TelegramTopicsSettings
+from ..transport_runtime import TransportRuntime
+from .client import BotClient
+from .topic_state import TopicStateStore, TopicThreadSnapshot
+from .types import TelegramIncomingMessage
+
+if TYPE_CHECKING:
+    from .bridge import TelegramBridgeConfig
+
+__all__ = [
+    "_TOPICS_COMMANDS",
+    "_maybe_rename_topic",
+    "_maybe_update_topic_context",
+    "_resolve_topics_scope",
+    "_topic_key",
+    "_topic_title",
+    "_topics_chat_allowed",
+    "_topics_chat_project",
+    "_topics_command_error",
+    "_topics_scope_label",
+    "_validate_topics_setup",
+]
+
+_TOPICS_COMMANDS = {"ctx", "new", "topic"}
+
+
+def _resolve_topics_scope_raw(
+    scope: str, chat_id: int, project_chat_ids: Iterable[int]
+) -> tuple[str, frozenset[int]]:
+    project_ids = set(project_chat_ids)
+    if scope == "auto":
+        scope = "projects" if project_ids else "main"
+    if scope == "main":
+        return scope, frozenset({chat_id})
+    if scope == "projects":
+        return scope, frozenset(project_ids)
+    if scope == "all":
+        return scope, frozenset({chat_id, *project_ids})
+    raise ValueError(f"Invalid topics.scope: {scope!r}")
+
+
+def _resolve_topics_scope(cfg: TelegramBridgeConfig) -> tuple[str, frozenset[int]]:
+    return _resolve_topics_scope_raw(
+        cfg.topics.scope, cfg.chat_id, cfg.runtime.project_chat_ids()
+    )
+
+
+def _topics_scope_label(cfg: TelegramBridgeConfig) -> str:
+    resolved, _ = _resolve_topics_scope(cfg)
+    if cfg.topics.scope == "auto":
+        return f"auto ({resolved})"
+    return resolved
+
+
+def _topics_chat_project(cfg: TelegramBridgeConfig, chat_id: int) -> str | None:
+    context = cfg.runtime.default_context_for_chat(chat_id)
+    return context.project if context is not None else None
+
+
+def _topics_chat_allowed(
+    cfg: TelegramBridgeConfig,
+    chat_id: int,
+    *,
+    scope_chat_ids: frozenset[int] | None = None,
+) -> bool:
+    if not cfg.topics.enabled:
+        return False
+    if scope_chat_ids is None:
+        _, scope_chat_ids = _resolve_topics_scope(cfg)
+    return chat_id in scope_chat_ids
+
+
+def _topics_command_error(
+    cfg: TelegramBridgeConfig,
+    chat_id: int,
+    *,
+    resolved_scope: str | None = None,
+    scope_chat_ids: frozenset[int] | None = None,
+) -> str | None:
+    if resolved_scope is None or scope_chat_ids is None:
+        resolved_scope, scope_chat_ids = _resolve_topics_scope(cfg)
+    if cfg.topics.enabled and chat_id in scope_chat_ids:
+        return None
+    if resolved_scope == "main":
+        if cfg.topics.scope == "auto":
+            return (
+                "topics commands are only available in the main chat (auto scope). "
+                'to use topics in project chats, set `topics.scope = "projects"`.'
+            )
+        return "topics commands are only available in the main chat."
+    if resolved_scope == "projects":
+        if cfg.topics.scope == "auto":
+            return (
+                "topics commands are only available in project chats (auto scope). "
+                'to use topics in the main chat, set `topics.scope = "main"`.'
+            )
+        return "topics commands are only available in project chats."
+    return "topics commands are only available in the main or project chats."
+
+
+def _topic_key(
+    msg: TelegramIncomingMessage,
+    cfg: TelegramBridgeConfig,
+    *,
+    scope_chat_ids: frozenset[int] | None = None,
+) -> tuple[int, int] | None:
+    if not cfg.topics.enabled:
+        return None
+    if not _topics_chat_allowed(cfg, msg.chat_id, scope_chat_ids=scope_chat_ids):
+        return None
+    if msg.thread_id is None:
+        return None
+    return (msg.chat_id, msg.thread_id)
+
+
+def _topic_title(*, runtime: TransportRuntime, context: RunContext) -> str:
+    project = (
+        runtime.project_alias_for_key(context.project)
+        if context.project is not None
+        else ""
+    )
+    if context.branch:
+        if project:
+            return f"{project} @{context.branch}"
+        return f"@{context.branch}"
+    return project or "topic"
+
+
+async def _maybe_rename_topic(
+    cfg: TelegramBridgeConfig,
+    store: TopicStateStore,
+    *,
+    chat_id: int,
+    thread_id: int,
+    context: RunContext,
+    snapshot: TopicThreadSnapshot | None = None,
+) -> None:
+    title = _topic_title(runtime=cfg.runtime, context=context)
+    if snapshot is None:
+        snapshot = await store.get_thread(chat_id, thread_id)
+    if snapshot is not None and snapshot.topic_title == title:
+        return
+    updated = await cfg.bot.edit_forum_topic(
+        chat_id=chat_id,
+        message_thread_id=thread_id,
+        name=title,
+    )
+    if not updated:
+        from ..logging import get_logger
+
+        logger = get_logger(__name__)
+        logger.warning(
+            "topics.rename.failed",
+            chat_id=chat_id,
+            thread_id=thread_id,
+            title=title,
+        )
+        return
+    await store.set_context(chat_id, thread_id, context, topic_title=title)
+
+
+async def _maybe_update_topic_context(
+    *,
+    cfg: TelegramBridgeConfig,
+    topic_store: TopicStateStore | None,
+    topic_key: tuple[int, int] | None,
+    context: RunContext | None,
+    context_source: str,
+) -> None:
+    if (
+        topic_store is None
+        or topic_key is None
+        or context is None
+        or context_source != "directives"
+    ):
+        return
+    await topic_store.set_context(topic_key[0], topic_key[1], context)
+    await _maybe_rename_topic(
+        cfg,
+        topic_store,
+        chat_id=topic_key[0],
+        thread_id=topic_key[1],
+        context=context,
+    )
+
+
+async def _validate_topics_setup(cfg: TelegramBridgeConfig) -> None:
+    await _validate_topics_setup_for(
+        bot=cfg.bot,
+        topics=cfg.topics,
+        chat_id=cfg.chat_id,
+        project_chat_ids=cfg.runtime.project_chat_ids(),
+    )
+
+
+async def _validate_topics_setup_for(
+    *,
+    bot: BotClient,
+    topics: TelegramTopicsSettings,
+    chat_id: int,
+    project_chat_ids: Iterable[int],
+) -> None:
+    if not topics.enabled:
+        return
+    me = await bot.get_me()
+    if me is None:
+        raise ConfigError("failed to fetch bot id for topics validation.")
+    bot_id = me.id
+    scope, chat_ids = _resolve_topics_scope_raw(topics.scope, chat_id, project_chat_ids)
+    if scope == "projects" and not chat_ids:
+        raise ConfigError(
+            "topics enabled but no project chats are configured; "
+            'set projects.<alias>.chat_id for forum chats or use scope="main".'
+        )
+
+    for chat_id in chat_ids:
+        chat = await bot.get_chat(chat_id)
+        if chat is None:
+            raise ConfigError(
+                f"failed to fetch chat info for topics validation ({chat_id})."
+            )
+        if chat.type != "supergroup":
+            raise ConfigError(
+                "topics enabled but chat is not a supergroup "
+                f"(chat_id={chat_id}); convert the group and enable topics."
+            )
+        if chat.is_forum is not True:
+            raise ConfigError(
+                "topics enabled but chat does not have topics enabled "
+                f"(chat_id={chat_id}); turn on topics in group settings."
+            )
+        member = await bot.get_chat_member(chat_id, bot_id)
+        if member is None:
+            raise ConfigError(
+                "failed to fetch bot permissions "
+                f"(chat_id={chat_id}); promote the bot to admin with manage topics."
+            )
+        if member.status == "creator":
+            continue
+        if member.status != "administrator":
+            raise ConfigError(
+                "topics enabled but bot is not an admin "
+                f"(chat_id={chat_id}); promote it and grant manage topics."
+            )
+        if member.can_manage_topics is not True:
+            raise ConfigError(
+                "topics enabled but bot lacks manage topics permission "
+                f"(chat_id={chat_id}); grant can_manage_topics."
+            )

yee88/telegram/trigger_mode.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from ..transport_runtime import TransportRuntime
+from .chat_prefs import ChatPrefsStore
+from .commands.parse import _parse_slash_command
+from .topic_state import TopicStateStore
+from .types import TelegramIncomingMessage
+
+TriggerMode = Literal["all", "mentions"]
+
+
+async def resolve_trigger_mode(
+    *,
+    chat_id: int,
+    thread_id: int | None,
+    chat_prefs: ChatPrefsStore | None,
+    topic_store: TopicStateStore | None,
+) -> TriggerMode:
+    if topic_store is not None and thread_id is not None:
+        topic_mode = await topic_store.get_trigger_mode(chat_id, thread_id)
+        if topic_mode == "mentions":
+            return "mentions"
+    if chat_prefs is not None:
+        chat_mode = await chat_prefs.get_trigger_mode(chat_id)
+        if chat_mode == "mentions":
+            return "mentions"
+    return "all"
+
+
+def should_trigger_run(
+    msg: TelegramIncomingMessage,
+    *,
+    bot_username: str | None,
+    runtime: TransportRuntime,
+    command_ids: set[str],
+    reserved_chat_commands: set[str],
+) -> bool:
+    text = msg.text or ""
+    lowered = text.lower()
+    if bot_username:
+        needle = f"@{bot_username}"
+        if needle in lowered:
+            return True
+    implicit_topic_reply = (
+        msg.thread_id is not None and msg.reply_to_message_id == msg.thread_id
+    )
+
+    if msg.reply_to_is_bot and not implicit_topic_reply:
+        return True
+    if (
+        bot_username
+        and msg.reply_to_username
+        and msg.reply_to_username.lower() == bot_username
+        and not implicit_topic_reply
+    ):
+        return True
+    command_id, _ = _parse_slash_command(text)
+    if not command_id:
+        return False
+    if command_id in reserved_chat_commands or command_id in command_ids:
+        return True
+    engine_ids = {engine.lower() for engine in runtime.available_engine_ids()}
+    if command_id in engine_ids:
+        return True
+    project_aliases = {alias.lower() for alias in runtime.project_aliases()}
+    return command_id in project_aliases