yee88 0.3.0__py3-none-any.whl

yee88/telegram/commands/trigger.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..chat_prefs import ChatPrefsStore
+from ..files import split_command_args
+from ..topic_state import TopicStateStore
+from ..topics import _topic_key
+from ..trigger_mode import resolve_trigger_mode
+from ..types import TelegramIncomingMessage
+from .overrides import check_admin_or_private
+from .plan import ActionPlan
+from .reply import make_reply
+
+if TYPE_CHECKING:
+    from ..bridge import TelegramBridgeConfig
+
+TRIGGER_USAGE = (
+    "usage: `/trigger`, `/trigger all`, `/trigger mentions`, or `/trigger clear`"
+)
+
+
+async def _handle_trigger_command(
+    cfg: TelegramBridgeConfig,
+    msg: TelegramIncomingMessage,
+    args_text: str,
+    _ambient_context,
+    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)
+    plan = await _plan_trigger_command(
+        cfg,
+        msg,
+        args_text=args_text,
+        topic_store=topic_store,
+        chat_prefs=chat_prefs,
+        scope_chat_ids=scope_chat_ids,
+    )
+    await plan.execute(reply)
+
+
+async def _plan_trigger_command(
+    cfg: TelegramBridgeConfig,
+    msg: TelegramIncomingMessage,
+    *,
+    args_text: str,
+    topic_store: TopicStateStore | None,
+    chat_prefs: ChatPrefsStore | None,
+    scope_chat_ids: frozenset[int] | None,
+) -> ActionPlan:
+    tkey = _topic_key(msg, cfg, scope_chat_ids=scope_chat_ids)
+    tokens = split_command_args(args_text)
+    action = tokens[0].lower() if tokens else "show"
+
+    if action in {"show", ""}:
+        resolved = await resolve_trigger_mode(
+            chat_id=msg.chat_id,
+            thread_id=msg.thread_id,
+            chat_prefs=chat_prefs,
+            topic_store=topic_store,
+        )
+        topic_mode = None
+        if tkey is not None and topic_store is not None:
+            topic_mode = await topic_store.get_trigger_mode(tkey[0], tkey[1])
+        chat_mode = None
+        if chat_prefs is not None:
+            chat_mode = await chat_prefs.get_trigger_mode(msg.chat_id)
+        if topic_mode is not None:
+            source = "topic override"
+        elif chat_mode is not None:
+            source = "chat default"
+        else:
+            source = "default"
+        trigger_line = f"trigger: {resolved} ({source})"
+        topic_label = topic_mode or "none"
+        if tkey is None:
+            topic_label = "none"
+        chat_label = "unavailable" if chat_prefs is None else chat_mode or "none"
+        defaults_line = f"defaults: topic: {topic_label}, chat: {chat_label}"
+        available_line = "available: all, mentions"
+        return ActionPlan(
+            reply_text="\n\n".join([trigger_line, defaults_line, available_line])
+        )
+
+    if action in {"all", "mentions"}:
+        decision = await check_admin_or_private(
+            cfg,
+            msg,
+            missing_sender="cannot verify sender for trigger settings.",
+            failed_member="failed to verify trigger permissions.",
+            denied="changing trigger mode is restricted to group admins.",
+        )
+        if not decision.allowed:
+            return ActionPlan(reply_text=decision.error_text or TRIGGER_USAGE)
+        if tkey is not None:
+            if topic_store is None:
+                return ActionPlan(reply_text="topic trigger settings are unavailable.")
+            return ActionPlan(
+                reply_text=f"topic trigger mode set to `{action}`",
+                actions=(
+                    lambda: topic_store.set_trigger_mode(tkey[0], tkey[1], action),
+                ),
+            )
+        if chat_prefs is None:
+            return ActionPlan(
+                reply_text="chat trigger settings are unavailable (no config path)."
+            )
+        return ActionPlan(
+            reply_text=f"chat trigger mode set to `{action}`",
+            actions=(lambda: chat_prefs.set_trigger_mode(msg.chat_id, action),),
+        )
+
+    if action == "clear":
+        decision = await check_admin_or_private(
+            cfg,
+            msg,
+            missing_sender="cannot verify sender for trigger settings.",
+            failed_member="failed to verify trigger permissions.",
+            denied="changing trigger mode is restricted to group admins.",
+        )
+        if not decision.allowed:
+            return ActionPlan(reply_text=decision.error_text or TRIGGER_USAGE)
+        if tkey is not None:
+            if topic_store is None:
+                return ActionPlan(reply_text="topic trigger settings are unavailable.")
+            return ActionPlan(
+                reply_text="topic trigger mode cleared (using chat default).",
+                actions=(lambda: topic_store.clear_trigger_mode(tkey[0], tkey[1]),),
+            )
+        if chat_prefs is None:
+            return ActionPlan(
+                reply_text="chat trigger settings are unavailable (no config path)."
+            )
+        return ActionPlan(
+            reply_text="chat trigger mode reset to `all`.",
+            actions=(lambda: chat_prefs.clear_trigger_mode(msg.chat_id),),
+        )
+
+    return ActionPlan(reply_text=TRIGGER_USAGE)

yee88/telegram/context.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..context import RunContext
+from ..transport_runtime import TransportRuntime
+from .topic_state import TopicThreadSnapshot
+from .topics import _topics_scope_label
+
+if TYPE_CHECKING:
+    from .bridge import TelegramBridgeConfig
+
+__all__ = [
+    "_format_context",
+    "_format_ctx_status",
+    "_merge_topic_context",
+    "_parse_project_branch_args",
+    "_usage_ctx_set",
+    "_usage_topic",
+]
+
+
+def _format_context(runtime: TransportRuntime, context: RunContext | None) -> str:
+    if context is None or context.project is None:
+        return "none"
+    project = runtime.project_alias_for_key(context.project)
+    if context.branch:
+        return f"{project} @{context.branch}"
+    return project
+
+
+def _usage_ctx_set(*, chat_project: str | None) -> str:
+    if chat_project is not None:
+        return "usage: `/ctx set [@branch]`"
+    return "usage: `/ctx set <project> [@branch]`"
+
+
+def _usage_topic(*, chat_project: str | None) -> str:
+    if chat_project is not None:
+        return "usage: `/topic @branch`"
+    return "usage: `/topic <project> @branch`"
+
+
+def _parse_project_branch_args(
+    args_text: str,
+    *,
+    runtime: TransportRuntime,
+    require_branch: bool,
+    chat_project: str | None,
+) -> tuple[RunContext | None, str | None]:
+    from .files import split_command_args
+
+    tokens = split_command_args(args_text)
+    if not tokens:
+        return (
+            None,
+            _usage_topic(chat_project=chat_project)
+            if require_branch
+            else _usage_ctx_set(chat_project=chat_project),
+        )
+    if len(tokens) > 2:
+        return None, "too many arguments"
+    project_token: str | None = None
+    branch: str | None = None
+    first = tokens[0]
+    if first.startswith("@"):
+        branch = first[1:] or None
+    else:
+        project_token = first
+        if len(tokens) == 2:
+            second = tokens[1]
+            if not second.startswith("@"):
+                return None, "branch must be prefixed with @"
+            branch = second[1:] or None
+
+    project_key: str | None = None
+    if chat_project is not None:
+        if project_token is None:
+            project_key = chat_project
+        else:
+            normalized = runtime.normalize_project_key(project_token)
+            if normalized is None:
+                return None, f"unknown project {project_token!r}"
+            if normalized != chat_project:
+                expected = runtime.project_alias_for_key(chat_project)
+                return None, (f"project mismatch for this chat; expected {expected!r}.")
+            project_key = normalized
+    else:
+        if project_token is None:
+            return None, "project is required"
+        project_key = runtime.normalize_project_key(project_token)
+        if project_key is None:
+            return None, f"unknown project {project_token!r}"
+
+    if require_branch and not branch:
+        return None, "branch is required"
+
+    return RunContext(project=project_key, branch=branch), None
+
+
+def _format_ctx_status(
+    *,
+    cfg: TelegramBridgeConfig,
+    runtime: TransportRuntime,
+    bound: RunContext | None,
+    resolved: RunContext | None,
+    context_source: str,
+    snapshot: TopicThreadSnapshot | None,
+    chat_project: str | None,
+) -> str:
+    lines = [
+        f"topics: enabled (scope={_topics_scope_label(cfg)})",
+        f"bound ctx: {_format_context(runtime, bound)}",
+        f"resolved ctx: {_format_context(runtime, resolved)} (source: {context_source})",
+    ]
+    if chat_project is None and bound is None:
+        topic_usage = (
+            _usage_topic(chat_project=chat_project).removeprefix("usage: ").strip()
+        )
+        ctx_usage = (
+            _usage_ctx_set(chat_project=chat_project).removeprefix("usage: ").strip()
+        )
+        lines.append(f"note: unbound topic — bind with {topic_usage} or {ctx_usage}")
+    sessions = None
+    if snapshot is not None and snapshot.sessions:
+        sessions = ", ".join(sorted(snapshot.sessions))
+    lines.append(f"sessions: {sessions or 'none'}")
+    return "\n".join(lines)
+
+
+def _merge_topic_context(
+    *, chat_project: str | None, bound: RunContext | None
+) -> RunContext | None:
+    if chat_project is None:
+        return bound
+    if bound is None:
+        return RunContext(project=chat_project, branch=None)
+    if bound.project is None:
+        return RunContext(project=chat_project, branch=bound.branch)
+    return bound

yee88/telegram/engine_defaults.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from ..context import RunContext
+from ..model import EngineId
+from ..transport_runtime import TransportRuntime
+from .chat_prefs import ChatPrefsStore
+from .topic_state import TopicStateStore
+
+EngineSource = Literal[
+    "directive",
+    "topic_default",
+    "chat_default",
+    "project_default",
+    "global_default",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class EngineResolution:
+    engine: EngineId
+    source: EngineSource
+    topic_default: EngineId | None
+    chat_default: EngineId | None
+    project_default: EngineId | None
+
+
+async def resolve_engine_for_message(
+    *,
+    runtime: TransportRuntime,
+    context: RunContext | None,
+    explicit_engine: EngineId | None,
+    chat_id: int,
+    topic_key: tuple[int, int] | None,
+    topic_store: TopicStateStore | None,
+    chat_prefs: ChatPrefsStore | None,
+) -> EngineResolution:
+    topic_default = None
+    if topic_store is not None and topic_key is not None:
+        topic_default = await topic_store.get_default_engine(*topic_key)
+    chat_default = None
+    if chat_prefs is not None:
+        chat_default = await chat_prefs.get_default_engine(chat_id)
+    project_default = runtime.project_default_engine(context)
+
+    if explicit_engine is not None:
+        return EngineResolution(
+            engine=explicit_engine,
+            source="directive",
+            topic_default=topic_default,
+            chat_default=chat_default,
+            project_default=project_default,
+        )
+    if topic_default is not None:
+        return EngineResolution(
+            engine=topic_default,
+            source="topic_default",
+            topic_default=topic_default,
+            chat_default=chat_default,
+            project_default=project_default,
+        )
+    if chat_default is not None:
+        return EngineResolution(
+            engine=chat_default,
+            source="chat_default",
+            topic_default=topic_default,
+            chat_default=chat_default,
+            project_default=project_default,
+        )
+    if project_default is not None:
+        return EngineResolution(
+            engine=project_default,
+            source="project_default",
+            topic_default=topic_default,
+            chat_default=chat_default,
+            project_default=project_default,
+        )
+    return EngineResolution(
+        engine=runtime.default_engine,
+        source="global_default",
+        topic_default=topic_default,
+        chat_default=chat_default,
+        project_default=project_default,
+    )

yee88/telegram/engine_overrides.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+import msgspec
+
+OverrideSource = Literal["topic_override", "chat_default", "default"]
+
+REASONING_LEVELS: tuple[str, ...] = ("minimal", "low", "medium", "high", "xhigh")
+REASONING_SUPPORTED_ENGINES = frozenset({"codex"})
+
+
+class EngineOverrides(msgspec.Struct, forbid_unknown_fields=False):
+    model: str | None = None
+    reasoning: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class OverrideValueResolution:
+    value: str | None
+    source: OverrideSource
+    topic_value: str | None
+    chat_value: str | None
+
+
+def normalize_override_value(value: str | None) -> str | None:
+    if value is None:
+        return None
+    cleaned = value.strip()
+    return cleaned or None
+
+
+def normalize_overrides(overrides: EngineOverrides | None) -> EngineOverrides | None:
+    if overrides is None:
+        return None
+    model = normalize_override_value(overrides.model)
+    reasoning = normalize_override_value(overrides.reasoning)
+    if model is None and reasoning is None:
+        return None
+    return EngineOverrides(model=model, reasoning=reasoning)
+
+
+def merge_overrides(
+    topic_override: EngineOverrides | None,
+    chat_override: EngineOverrides | None,
+) -> EngineOverrides | None:
+    topic = normalize_overrides(topic_override)
+    chat = normalize_overrides(chat_override)
+    if topic is None and chat is None:
+        return None
+    model = None
+    reasoning = None
+    if topic is not None and topic.model is not None:
+        model = topic.model
+    elif chat is not None:
+        model = chat.model
+    if topic is not None and topic.reasoning is not None:
+        reasoning = topic.reasoning
+    elif chat is not None:
+        reasoning = chat.reasoning
+    return normalize_overrides(EngineOverrides(model=model, reasoning=reasoning))
+
+
+def resolve_override_value(
+    *,
+    topic_override: EngineOverrides | None,
+    chat_override: EngineOverrides | None,
+    field: Literal["model", "reasoning"],
+) -> OverrideValueResolution:
+    topic_value = normalize_override_value(
+        getattr(topic_override, field, None) if topic_override is not None else None
+    )
+    chat_value = normalize_override_value(
+        getattr(chat_override, field, None) if chat_override is not None else None
+    )
+    if topic_value is not None:
+        return OverrideValueResolution(
+            value=topic_value,
+            source="topic_override",
+            topic_value=topic_value,
+            chat_value=chat_value,
+        )
+    if chat_value is not None:
+        return OverrideValueResolution(
+            value=chat_value,
+            source="chat_default",
+            topic_value=topic_value,
+            chat_value=chat_value,
+        )
+    return OverrideValueResolution(
+        value=None,
+        source="default",
+        topic_value=topic_value,
+        chat_value=chat_value,
+    )
+
+
+def allowed_reasoning_levels(engine: str) -> tuple[str, ...]:
+    _ = engine
+    return REASONING_LEVELS
+
+
+def supports_reasoning(engine: str) -> bool:
+    return engine in REASONING_SUPPORTED_ENGINES

yee88/telegram/files.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import io
+import os
+import shlex
+import tempfile
+import zipfile
+from collections.abc import Sequence
+from pathlib import Path, PurePosixPath
+
+__all__ = [
+    "ZipTooLargeError",
+    "default_upload_name",
+    "default_upload_path",
+    "deny_reason",
+    "file_usage",
+    "format_bytes",
+    "normalize_relative_path",
+    "parse_file_command",
+    "parse_file_prompt",
+    "resolve_path_within_root",
+    "split_command_args",
+    "write_bytes_atomic",
+    "zip_directory",
+]
+
+
+def split_command_args(text: str) -> tuple[str, ...]:
+    if not text.strip():
+        return ()
+    try:
+        return tuple(shlex.split(text))
+    except ValueError:
+        return tuple(text.split())
+
+
+def file_usage() -> str:
+    return "usage: `/file put <path>` or `/file get <path>`"
+
+
+def parse_file_command(args_text: str) -> tuple[str | None, str, str | None]:
+    tokens = split_command_args(args_text)
+    if not tokens:
+        return None, "", file_usage()
+    command = tokens[0].lower()
+    rest = " ".join(tokens[1:]).strip()
+    if command not in {"put", "get"}:
+        return None, rest, file_usage()
+    return command, rest, None
+
+
+def parse_file_prompt(
+    prompt: str, *, allow_empty: bool
+) -> tuple[str | None, bool, str | None]:
+    tokens = split_command_args(prompt)
+    force = False
+    parts: list[str] = []
+    for token in tokens:
+        if token == "--force":
+            force = True
+            continue
+        if token.startswith("--"):
+            return None, force, f"unknown flag: {token}"
+        parts.append(token)
+    path = " ".join(parts).strip()
+    if not path and not allow_empty:
+        return None, force, "missing path"
+    return (path or None), force, None
+
+
+def normalize_relative_path(value: str) -> Path | None:
+    cleaned = value.strip()
+    if not cleaned:
+        return None
+    if cleaned.startswith("~"):
+        return None
+    path = Path(cleaned)
+    if path.is_absolute():
+        return None
+    parts = [part for part in path.parts if part not in {"", "."}]
+    if not parts:
+        return None
+    if ".." in parts:
+        return None
+    if ".git" in parts:
+        return None
+    return Path(*parts)
+
+
+def resolve_path_within_root(root: Path, rel_path: Path) -> Path | None:
+    root_resolved = root.resolve(strict=False)
+    target = (root / rel_path).resolve(strict=False)
+    if not target.is_relative_to(root_resolved):
+        return None
+    return target
+
+
+def deny_reason(rel_path: Path, deny_globs: Sequence[str]) -> str | None:
+    if ".git" in rel_path.parts:
+        return ".git/**"
+    posix = PurePosixPath(rel_path.as_posix())
+    for pattern in deny_globs:
+        if posix.match(pattern):
+            return pattern
+    return None
+
+
+def format_bytes(value: int) -> str:
+    size = max(0.0, float(value))
+    units = ("b", "kb", "mb", "gb", "tb")
+    for unit in units:
+        if size < 1024 or unit == units[-1]:
+            if unit == "b":
+                return f"{int(size)} b"
+            if size < 10:
+                return f"{size:.1f} {unit}"
+            return f"{size:.0f} {unit}"
+        size /= 1024
+    return f"{int(size)} B"
+
+
+def default_upload_name(filename: str | None, file_path: str | None) -> str:
+    name = Path(filename or "").name
+    if not name and file_path:
+        name = Path(file_path).name
+    if not name:
+        name = "upload.bin"
+    return name
+
+
+def default_upload_path(
+    uploads_dir: str, filename: str | None, file_path: str | None
+) -> Path:
+    return Path(uploads_dir) / default_upload_name(filename, file_path)
+
+
+def write_bytes_atomic(path: Path, payload: bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile(
+        mode="wb", delete=False, dir=path.parent, prefix=".yee88-upload-"
+    ) as handle:
+        handle.write(payload)
+        temp_name = handle.name
+    Path(temp_name).replace(path)
+
+
+class ZipTooLargeError(Exception):
+    pass
+
+
+def zip_directory(
+    root: Path,
+    rel_path: Path,
+    deny_globs: Sequence[str],
+    *,
+    max_bytes: int | None = None,
+) -> bytes:
+    target = root / rel_path
+    buffer = io.BytesIO()
+    with zipfile.ZipFile(buffer, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+        for dirpath, _, filenames in os.walk(target, followlinks=False):
+            dir_path = Path(dirpath)
+            for filename in filenames:
+                item = dir_path / filename
+                if item.is_symlink():
+                    continue
+                if not item.is_file():
+                    continue
+                rel_item = rel_path / item.relative_to(target)
+                if deny_reason(rel_item, deny_globs) is not None:
+                    continue
+                archive.write(item, arcname=rel_item.as_posix())
+                if max_bytes is not None and buffer.tell() > max_bytes:
+                    raise ZipTooLargeError()
+    payload = buffer.getvalue()
+    if max_bytes is not None and len(payload) > max_bytes:
+        raise ZipTooLargeError()
+    return payload