yee88 0.3.0__py3-none-any.whl

yee88/telegram/commands/media.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Sequence
+from typing import TYPE_CHECKING
+
+from ...context import RunContext
+from ...directives import DirectiveError
+from ...transport_runtime import ResolvedMessage
+from ..context import _merge_topic_context
+from ..files import parse_file_command
+from ..topic_state import TopicStateStore
+from ..topics import _topic_key, _topics_chat_project
+from ..types import TelegramIncomingMessage
+from .file_transfer import (
+    FILE_PUT_USAGE,
+    _format_file_put_failures,
+    _handle_file_put_group,
+    _save_file_put_group,
+)
+from .parse import _parse_slash_command
+from .reply import make_reply
+
+if TYPE_CHECKING:
+    from ..bridge import TelegramBridgeConfig
+
+
+async def _handle_media_group(
+    cfg: TelegramBridgeConfig,
+    messages: Sequence[TelegramIncomingMessage],
+    topic_store: TopicStateStore | None,
+    run_prompt: Callable[
+        [TelegramIncomingMessage, str, ResolvedMessage], Awaitable[None]
+    ]
+    | None = None,
+    resolve_prompt: Callable[
+        [TelegramIncomingMessage, str, RunContext | None],
+        Awaitable[ResolvedMessage | None],
+    ]
+    | None = None,
+) -> None:
+    if not messages:
+        return
+    ordered = sorted(messages, key=lambda item: item.message_id)
+    command_msg = next(
+        (item for item in ordered if item.text.strip()),
+        ordered[0],
+    )
+    reply = make_reply(cfg, command_msg)
+    topic_key = _topic_key(command_msg, cfg) if topic_store is not None else None
+    chat_project = _topics_chat_project(cfg, command_msg.chat_id)
+    bound_context = (
+        await topic_store.get_context(*topic_key)
+        if topic_store is not None and topic_key is not None
+        else None
+    )
+    ambient_context = _merge_topic_context(
+        chat_project=chat_project, bound=bound_context
+    )
+    command_id, args_text = _parse_slash_command(command_msg.text)
+    if command_id == "file":
+        command, rest, error = parse_file_command(args_text)
+        if error is not None:
+            await reply(text=error)
+            return
+        if command == "put":
+            await _handle_file_put_group(
+                cfg,
+                command_msg,
+                rest,
+                ordered,
+                ambient_context,
+                topic_store,
+            )
+            return
+    if cfg.files.enabled and cfg.files.auto_put:
+        caption_text = command_msg.text.strip()
+        if cfg.files.auto_put_mode == "prompt" and caption_text:
+            if resolve_prompt is None:
+                try:
+                    resolved = cfg.runtime.resolve_message(
+                        text=caption_text,
+                        reply_text=command_msg.reply_to_text,
+                        ambient_context=ambient_context,
+                        chat_id=command_msg.chat_id,
+                    )
+                except DirectiveError as exc:
+                    await reply(text=f"error:\n{exc}")
+                    return
+            else:
+                resolved = await resolve_prompt(
+                    command_msg, caption_text, ambient_context
+                )
+            if resolved is None:
+                return
+            saved_group = await _save_file_put_group(
+                cfg,
+                command_msg,
+                "",
+                ordered,
+                resolved.context,
+                topic_store,
+            )
+            if saved_group is None:
+                return
+            if not saved_group.saved:
+                failure_text = _format_file_put_failures(saved_group.failed)
+                text = "failed to upload files."
+                if failure_text is not None:
+                    text = f"{text}\n\n{failure_text}"
+                await reply(text=text)
+                return
+            if saved_group.failed:
+                failure_text = _format_file_put_failures(saved_group.failed)
+                if failure_text is not None:
+                    await reply(text=f"some files failed to upload.\n\n{failure_text}")
+            if run_prompt is None:
+                await reply(text=FILE_PUT_USAGE)
+                return
+            paths = [
+                item.rel_path.as_posix()
+                for item in saved_group.saved
+                if item.rel_path is not None
+            ]
+            files_text = "\n".join(f"- {path}" for path in paths)
+            prompt_base = resolved.prompt
+            annotation = f"[uploaded files]\n{files_text}"
+            if prompt_base and prompt_base.strip():
+                prompt = f"{prompt_base}\n\n{annotation}"
+            else:
+                prompt = annotation
+            await run_prompt(command_msg, prompt, resolved)
+            return
+        if not caption_text:
+            await _handle_file_put_group(
+                cfg,
+                command_msg,
+                "",
+                ordered,
+                ambient_context,
+                topic_store,
+            )
+            return
+    await reply(text=FILE_PUT_USAGE)

yee88/telegram/commands/menu.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ...commands import get_command
+from ...config import ConfigError
+from ...ids import RESERVED_COMMAND_IDS, is_valid_id
+from ...logging import get_logger
+from ...plugins import COMMAND_GROUP, list_entrypoints
+from ...transport_runtime import TransportRuntime
+
+if TYPE_CHECKING:
+    from ..bridge import TelegramBridgeConfig
+
+logger = get_logger(__name__)
+
+_MAX_BOT_COMMANDS = 100
+
+
+def build_bot_commands(
+    runtime: TransportRuntime,
+    *,
+    include_file: bool = True,
+    include_topics: bool = False,
+) -> list[dict[str, str]]:
+    commands: list[dict[str, str]] = []
+    seen: set[str] = set()
+    for engine_id in runtime.available_engine_ids():
+        cmd = engine_id.lower()
+        if cmd in seen:
+            continue
+        commands.append({"command": cmd, "description": f"use engine: {cmd}"})
+        seen.add(cmd)
+    for alias in runtime.project_aliases():
+        cmd = alias.lower()
+        if cmd in seen:
+            continue
+        if not is_valid_id(cmd):
+            logger.debug(
+                "startup.command_menu.skip_project",
+                alias=alias,
+            )
+            continue
+        commands.append({"command": cmd, "description": f"work on: {cmd}"})
+        seen.add(cmd)
+    allowlist = runtime.allowlist
+    for ep in list_entrypoints(
+        COMMAND_GROUP,
+        allowlist=allowlist,
+        reserved_ids=RESERVED_COMMAND_IDS,
+    ):
+        try:
+            backend = get_command(ep.name, allowlist=allowlist)
+        except ConfigError as exc:
+            logger.info(
+                "startup.command_menu.skip_command",
+                command=ep.name,
+                error=str(exc),
+            )
+            continue
+        cmd = backend.id.lower()
+        if cmd in seen:
+            continue
+        if not is_valid_id(cmd):
+            logger.debug(
+                "startup.command_menu.skip_command_id",
+                command=cmd,
+            )
+            continue
+        description = backend.description or f"command: {cmd}"
+        commands.append({"command": cmd, "description": description})
+        seen.add(cmd)
+    for cmd, description in [
+        ("new", "start a new thread"),
+        ("ctx", "show or update context"),
+        ("agent", "set default engine"),
+        ("model", "set model override"),
+        ("reasoning", "set reasoning override"),
+        ("trigger", "set trigger mode"),
+    ]:
+        if cmd in seen:
+            continue
+        commands.append({"command": cmd, "description": description})
+        seen.add(cmd)
+    if include_topics:
+        for cmd, description in [("topic", "create or bind a topic")]:
+            if cmd in seen:
+                continue
+            commands.append({"command": cmd, "description": description})
+            seen.add(cmd)
+    if include_file and "file" not in seen:
+        commands.append({"command": "file", "description": "upload or fetch files"})
+        seen.add("file")
+    if "cancel" not in seen:
+        commands.append({"command": "cancel", "description": "cancel run"})
+    if len(commands) > _MAX_BOT_COMMANDS:
+        logger.warning(
+            "startup.command_menu.too_many",
+            count=len(commands),
+            limit=_MAX_BOT_COMMANDS,
+        )
+        commands = commands[:_MAX_BOT_COMMANDS]
+        if not any(cmd["command"] == "cancel" for cmd in commands):
+            commands[-1] = {"command": "cancel", "description": "cancel run"}
+    return commands
+
+
+def _reserved_commands(runtime: TransportRuntime) -> set[str]:
+    return {
+        *{engine.lower() for engine in runtime.engine_ids},
+        *{alias.lower() for alias in runtime.project_aliases()},
+        *RESERVED_COMMAND_IDS,
+    }
+
+
+async def _set_command_menu(cfg: TelegramBridgeConfig) -> None:
+    commands = build_bot_commands(
+        cfg.runtime,
+        include_file=cfg.files.enabled,
+        include_topics=cfg.topics.enabled,
+    )
+    if not commands:
+        return
+    try:
+        ok = await cfg.bot.set_my_commands(commands)
+    except Exception as exc:  # noqa: BLE001
+        logger.info(
+            "startup.command_menu.failed",
+            error=str(exc),
+            error_type=exc.__class__.__name__,
+        )
+        return
+    if not ok:
+        logger.info("startup.command_menu.rejected")
+        return
+    logger.info(
+        "startup.command_menu.updated",
+        commands=[cmd["command"] for cmd in commands],
+    )

yee88/telegram/commands/model.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ...context import RunContext
+from ..chat_prefs import ChatPrefsStore
+from ..engine_overrides import EngineOverrides, resolve_override_value
+from ..files import split_command_args
+from ..topic_state import TopicStateStore
+from ..topics import _topic_key
+from ..types import TelegramIncomingMessage
+from .overrides import (
+    ENGINE_SOURCE_LABELS,
+    OVERRIDE_SOURCE_LABELS,
+    apply_engine_override,
+    parse_set_args,
+    require_admin_or_private,
+    resolve_engine_selection,
+)
+from .reply import make_reply
+
+if TYPE_CHECKING:
+    from ..bridge import TelegramBridgeConfig
+
+MODEL_USAGE = (
+    "usage: `/model`, `/model set <model>`, "
+    "`/model set <engine> <model>`, or `/model clear [engine]`"
+)
+
+
+async def _handle_model_command(
+    cfg: TelegramBridgeConfig,
+    msg: TelegramIncomingMessage,
+    args_text: str,
+    ambient_context: RunContext | None,
+    topic_store: TopicStateStore | None,
+    chat_prefs: ChatPrefsStore | None,
+    *,
+    resolved_scope: str | None = None,
+    scope_chat_ids: frozenset[int] | None = None,
+) -> None:
+    reply = make_reply(cfg, msg)
+    tkey = (
+        _topic_key(msg, cfg, scope_chat_ids=scope_chat_ids)
+        if topic_store is not None
+        else None
+    )
+    tokens = split_command_args(args_text)
+    action = tokens[0].lower() if tokens else "show"
+    engine_ids = {engine.lower() for engine in cfg.runtime.engine_ids}
+
+    if action in {"show", ""}:
+        selection = await resolve_engine_selection(
+            cfg,
+            msg,
+            ambient_context=ambient_context,
+            topic_store=topic_store,
+            chat_prefs=chat_prefs,
+            topic_key=tkey,
+        )
+        if selection is None:
+            return
+        engine, engine_source = selection
+        topic_override = None
+        if tkey is not None and topic_store is not None:
+            topic_override = await topic_store.get_engine_override(
+                tkey[0], tkey[1], engine
+            )
+        chat_override = None
+        if chat_prefs is not None:
+            chat_override = await chat_prefs.get_engine_override(msg.chat_id, engine)
+        resolution = resolve_override_value(
+            topic_override=topic_override,
+            chat_override=chat_override,
+            field="model",
+        )
+        engine_line = f"engine: {engine} ({ENGINE_SOURCE_LABELS[engine_source]})"
+        model_value = resolution.value or "default"
+        model_line = (
+            f"model: {model_value} ({OVERRIDE_SOURCE_LABELS[resolution.source]})"
+        )
+        topic_label = resolution.topic_value or "none"
+        if tkey is None:
+            topic_label = "none"
+        chat_label = (
+            "unavailable" if chat_prefs is None else resolution.chat_value or "none"
+        )
+        defaults_line = f"defaults: topic: {topic_label}, chat: {chat_label}"
+        available_line = f"available engines: {', '.join(cfg.runtime.engine_ids)}"
+        await reply(
+            text="\n\n".join([engine_line, model_line, defaults_line, available_line])
+        )
+        return
+
+    if action == "set":
+        engine_arg, model = parse_set_args(tokens, engine_ids=engine_ids)
+        if model is None:
+            await reply(text=MODEL_USAGE)
+            return
+        if not await require_admin_or_private(
+            cfg,
+            msg,
+            missing_sender="cannot verify sender for model overrides.",
+            failed_member="failed to verify model override permissions.",
+            denied="changing model overrides is restricted to group admins.",
+        ):
+            return
+        if engine_arg is None:
+            selection = await resolve_engine_selection(
+                cfg,
+                msg,
+                ambient_context=ambient_context,
+                topic_store=topic_store,
+                chat_prefs=chat_prefs,
+                topic_key=tkey,
+            )
+            if selection is None:
+                return
+            engine, _ = selection
+        else:
+            engine = engine_arg
+            if engine not in engine_ids:
+                available = ", ".join(cfg.runtime.engine_ids)
+                await reply(
+                    text=f"unknown engine `{engine}`.\navailable engines: `{available}`"
+                )
+                return
+        scope = await apply_engine_override(
+            reply=reply,
+            tkey=tkey,
+            topic_store=topic_store,
+            chat_prefs=chat_prefs,
+            chat_id=msg.chat_id,
+            engine=engine,
+            update=lambda current: EngineOverrides(
+                model=model,
+                reasoning=current.reasoning if current is not None else None,
+            ),
+            topic_unavailable="topic model overrides are unavailable.",
+            chat_unavailable="chat model overrides are unavailable (no config path).",
+        )
+        if scope is None:
+            return
+        if scope == "topic":
+            await reply(
+                text=(
+                    f"topic model override set to `{model}` for `{engine}`.\n"
+                    "If you want a clean start on the new model, run `/new`."
+                )
+            )
+            return
+        await reply(
+            text=(
+                f"chat model override set to `{model}` for `{engine}`.\n"
+                "If you want a clean start on the new model, run `/new`."
+            )
+        )
+        return
+
+    if action == "clear":
+        engine = None
+        if len(tokens) > 2:
+            await reply(text=MODEL_USAGE)
+            return
+        if len(tokens) == 2:
+            engine = tokens[1].strip().lower() or None
+        if not await require_admin_or_private(
+            cfg,
+            msg,
+            missing_sender="cannot verify sender for model overrides.",
+            failed_member="failed to verify model override permissions.",
+            denied="changing model overrides is restricted to group admins.",
+        ):
+            return
+        if engine is None:
+            selection = await resolve_engine_selection(
+                cfg,
+                msg,
+                ambient_context=ambient_context,
+                topic_store=topic_store,
+                chat_prefs=chat_prefs,
+                topic_key=tkey,
+            )
+            if selection is None:
+                return
+            engine, _ = selection
+        if engine not in engine_ids:
+            available = ", ".join(cfg.runtime.engine_ids)
+            await reply(
+                text=f"unknown engine `{engine}`.\navailable engines: `{available}`"
+            )
+            return
+        scope = await apply_engine_override(
+            reply=reply,
+            tkey=tkey,
+            topic_store=topic_store,
+            chat_prefs=chat_prefs,
+            chat_id=msg.chat_id,
+            engine=engine,
+            update=lambda current: EngineOverrides(
+                model=None,
+                reasoning=current.reasoning if current is not None else None,
+            ),
+            topic_unavailable="topic model overrides are unavailable.",
+            chat_unavailable="chat model overrides are unavailable (no config path).",
+        )
+        if scope is None:
+            return
+        if scope == "topic":
+            await reply(text="topic model override cleared (using chat default).")
+            return
+        await reply(text="chat model override cleared.")
+        return
+
+    await reply(text=MODEL_USAGE)

yee88/telegram/commands/overrides.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+from ...context import RunContext
+from ...directives import DirectiveError
+from ..chat_prefs import ChatPrefsStore
+from ..engine_defaults import resolve_engine_for_message
+from ..engine_overrides import EngineOverrides
+from ..topic_state import TopicStateStore
+from ..types import TelegramIncomingMessage
+from .reply import make_reply
+
+if TYPE_CHECKING:
+    from ..bridge import TelegramBridgeConfig
+
+ENGINE_SOURCE_LABELS = {
+    "directive": "directive",
+    "topic_default": "topic default",
+    "chat_default": "chat default",
+    "project_default": "project default",
+    "global_default": "global default",
+}
+OVERRIDE_SOURCE_LABELS = {
+    "topic_override": "topic override",
+    "chat_default": "chat default",
+    "default": "no override",
+}
+
+
+async def require_admin_or_private(
+    cfg: TelegramBridgeConfig,
+    msg: TelegramIncomingMessage,
+    *,
+    missing_sender: str,
+    failed_member: str,
+    denied: str,
+) -> bool:
+    reply = make_reply(cfg, msg)
+    decision = await check_admin_or_private(
+        cfg,
+        msg,
+        missing_sender=missing_sender,
+        failed_member=failed_member,
+        denied=denied,
+    )
+    if decision.allowed:
+        return True
+    if decision.error_text is not None:
+        await reply(text=decision.error_text)
+    return False
+
+
+@dataclass(frozen=True, slots=True)
+class PermissionDecision:
+    allowed: bool
+    error_text: str | None = None
+
+
+async def check_admin_or_private(
+    cfg: TelegramBridgeConfig,
+    msg: TelegramIncomingMessage,
+    *,
+    missing_sender: str,
+    failed_member: str,
+    denied: str,
+) -> PermissionDecision:
+    sender_id = msg.sender_id
+    if sender_id is None:
+        return PermissionDecision(allowed=False, error_text=missing_sender)
+    if msg.is_private:
+        return PermissionDecision(allowed=True)
+    member = await cfg.bot.get_chat_member(msg.chat_id, sender_id)
+    if member is None:
+        return PermissionDecision(allowed=False, error_text=failed_member)
+    if member.status in {"creator", "administrator"}:
+        return PermissionDecision(allowed=True)
+    return PermissionDecision(allowed=False, error_text=denied)
+
+
+async def resolve_engine_selection(
+    cfg: TelegramBridgeConfig,
+    msg: TelegramIncomingMessage,
+    *,
+    ambient_context: RunContext | None,
+    topic_store: TopicStateStore | None,
+    chat_prefs: ChatPrefsStore | None,
+    topic_key: tuple[int, int] | None,
+) -> tuple[str, str] | None:
+    reply = make_reply(cfg, msg)
+    try:
+        resolved = cfg.runtime.resolve_message(
+            text="",
+            reply_text=msg.reply_to_text,
+            ambient_context=ambient_context,
+            chat_id=msg.chat_id,
+        )
+    except DirectiveError as exc:
+        await reply(text=f"error:\n{exc}")
+        return None
+    selection = await resolve_engine_for_message(
+        runtime=cfg.runtime,
+        context=resolved.context,
+        explicit_engine=None,
+        chat_id=msg.chat_id,
+        topic_key=topic_key,
+        topic_store=topic_store,
+        chat_prefs=chat_prefs,
+    )
+    return selection.engine, selection.source
+
+
+def parse_set_args(
+    tokens: tuple[str, ...], *, engine_ids: set[str]
+) -> tuple[str | None, str | None]:
+    if len(tokens) < 2:
+        return None, None
+    if len(tokens) == 2:
+        maybe_engine = tokens[1].strip().lower()
+        if maybe_engine in engine_ids:
+            return None, None
+        return None, tokens[1].strip()
+    maybe_engine = tokens[1].strip().lower()
+    if maybe_engine in engine_ids:
+        value = " ".join(tokens[2:]).strip()
+        return maybe_engine, value or None
+    value = " ".join(tokens[1:]).strip()
+    return None, value or None
+
+
+async def apply_engine_override(
+    *,
+    reply: Callable[..., Awaitable[None]],
+    tkey: tuple[int, int] | None,
+    topic_store: TopicStateStore | None,
+    chat_prefs: ChatPrefsStore | None,
+    chat_id: int,
+    engine: str,
+    update: Callable[[EngineOverrides | None], EngineOverrides],
+    topic_unavailable: str,
+    chat_unavailable: str,
+) -> Literal["topic", "chat"] | None:
+    if tkey is not None:
+        if topic_store is None:
+            await reply(text=topic_unavailable)
+            return None
+        current = await topic_store.get_engine_override(tkey[0], tkey[1], engine)
+        updated = update(current)
+        await topic_store.set_engine_override(tkey[0], tkey[1], engine, updated)
+        return "topic"
+    if chat_prefs is None:
+        await reply(text=chat_unavailable)
+        return None
+    current = await chat_prefs.get_engine_override(chat_id, engine)
+    updated = update(current)
+    await chat_prefs.set_engine_override(chat_id, engine, updated)
+    return "chat"

yee88/telegram/commands/parse.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+
+def is_cancel_command(text: str) -> bool:
+    stripped = text.strip()
+    if not stripped:
+        return False
+    command = stripped.split(maxsplit=1)[0]
+    return command == "/cancel" or command.startswith("/cancel@")
+
+
+def _parse_slash_command(text: str) -> tuple[str | None, str]:
+    stripped = text.lstrip()
+    if not stripped.startswith("/"):
+        return None, text
+    lines = stripped.splitlines()
+    if not lines:
+        return None, text
+    first_line = lines[0]
+    token, _, rest = first_line.partition(" ")
+    command = token[1:]
+    if not command:
+        return None, text
+    if "@" in command:
+        command = command.split("@", 1)[0]
+    args_text = rest
+    if len(lines) > 1:
+        tail = "\n".join(lines[1:])
+        args_text = f"{args_text}\n{tail}" if args_text else tail
+    return command.lower(), args_text

yee88/telegram/commands/plan.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class ActionPlan:
+    reply_text: str | None
+    actions: tuple[Callable[[], Awaitable[None]], ...] = ()
+
+    async def execute(self, reply: Callable[..., Awaitable[None]]) -> None:
+        for action in self.actions:
+            await action()
+        if self.reply_text is not None:
+            await reply(text=self.reply_text)