coding-agent-telegram 2026.3.26__py3-none-any.whl

coding_agent_telegram/__init__.py

@@ -0,0 +1,4 @@
+"""coding_agent_telegram package."""
+
+__all__ = ["__version__"]
+__version__ = "2026.03.26"

coding_agent_telegram/__main__.py

@@ -0,0 +1,5 @@
+from coding_agent_telegram.cli import main
+
+
+if __name__ == "__main__":
+    main()

coding_agent_telegram/agent_runner.py

@@ -0,0 +1,438 @@
+from __future__ import annotations
+
+import json
+import logging
+import os
+import subprocess
+import tempfile
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Optional, Sequence, Tuple, Union
+
+
+logger = logging.getLogger(__name__)
+
+AssistantEvent = Union[dict[str, Any], list[Any], str]
+
+
+@dataclass
+class AgentRunResult:
+    session_id: Optional[str]
+    success: bool
+    assistant_text: str
+    error_message: Optional[str]
+    raw_events: list[dict]
+
+
+@dataclass(frozen=True)
+class AgentStallInfo:
+    command: tuple[str, ...]
+    elapsed_seconds: float
+    idle_seconds: float
+    seen_output: bool
+    last_stderr: str
+
+
+class MultiAgentRunner:
+    """Runs supported local agent CLIs while preserving session behavior."""
+
+    STALL_WARNING_AFTER_SECONDS = 60.0
+    STALL_POLL_INTERVAL_SECONDS = 0.5
+    PROMPT_PREFIX = (
+        "Treat the current on-disk workspace as the source of truth. "
+        "Re-read relevant files from disk before making claims or edits. "
+    )
+
+    def __init__(
+        self,
+        codex_bin: str,
+        copilot_bin: str,
+        approval_policy: str,
+        sandbox_mode: str,
+        codex_model: str = "",
+        copilot_model: str = "",
+        copilot_autopilot: bool = True,
+        copilot_no_ask_user: bool = True,
+        copilot_allow_all: bool = True,
+        copilot_allow_all_tools: bool = False,
+        copilot_allow_tools: tuple[str, ...] = (),
+        copilot_deny_tools: tuple[str, ...] = (),
+        copilot_available_tools: tuple[str, ...] = (),
+    ) -> None:
+        self.codex_bin = codex_bin
+        self.copilot_bin = copilot_bin
+        self.approval_policy = approval_policy
+        self.sandbox_mode = sandbox_mode
+        self.codex_model = codex_model.strip()
+        self.copilot_model = copilot_model.strip()
+        self.copilot_autopilot = copilot_autopilot
+        self.copilot_no_ask_user = copilot_no_ask_user
+        self.copilot_allow_all = copilot_allow_all
+        self.copilot_allow_all_tools = copilot_allow_all_tools
+        self.copilot_allow_tools = tuple(tool.strip() for tool in copilot_allow_tools if tool.strip())
+        self.copilot_deny_tools = tuple(tool.strip() for tool in copilot_deny_tools if tool.strip())
+        self.copilot_available_tools = tuple(tool.strip() for tool in copilot_available_tools if tool.strip())
+
+    def _extract_assistant_text(self, event: AssistantEvent) -> str:
+        if isinstance(event, str):
+            return event
+        if isinstance(event, list):
+            return "\n".join(filter(None, [self._extract_assistant_text(item) for item in event]))
+        if not isinstance(event, dict):
+            return ""
+
+        chunks: list[str] = []
+        if isinstance(event.get("assistant_text"), str):
+            chunks.append(event["assistant_text"])
+
+        role = event.get("role")
+        event_type = event.get("type")
+        if role == "assistant" or event_type in {"message", "assistant_message", "output_text", "text"}:
+            for key in ("text", "message", "content"):
+                value = event.get(key)
+                extracted = self._extract_assistant_text(value)
+                if extracted:
+                    chunks.append(extracted)
+
+        for item in event.values():
+            if isinstance(item, (dict, list)):
+                extracted = self._extract_assistant_text(item)
+                if extracted:
+                    chunks.append(extracted)
+
+        unique_chunks: list[str] = []
+        for chunk in chunks:
+            cleaned = chunk.strip()
+            if cleaned and cleaned not in unique_chunks:
+                unique_chunks.append(cleaned)
+        return "\n".join(unique_chunks)
+
+    def _parse_jsonl(self, stdout: str) -> Tuple[Optional[str], bool, str, Optional[str], list[dict]]:
+        events: list[dict] = []
+        for line in stdout.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                events.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+
+        session_id = None
+        success = True
+        assistant_text = ""
+        error_message = None
+
+        for ev in events:
+            for key in ("session_id", "thread_id", "sessionId", "threadId"):
+                if isinstance(ev.get(key), str):
+                    session_id = ev[key]
+            extracted_text = self._extract_assistant_text(ev)
+            if extracted_text:
+                assistant_text = extracted_text
+            if isinstance(ev.get("error"), str):
+                error_message = ev["error"]
+            if isinstance(ev.get("message"), str) and ev.get("type") == "error":
+                error_message = ev["message"]
+            if isinstance(ev.get("success"), bool):
+                success = ev["success"]
+
+        return session_id, success, assistant_text, error_message, events
+
+    def _run(
+        self,
+        args: list[str],
+        *,
+        cwd: Optional[Path] = None,
+        env: Optional[dict[str, str]] = None,
+        on_stall: Optional[Callable[[AgentStallInfo], None]] = None,
+    ) -> AgentRunResult:
+        proc = subprocess.Popen(
+            args,
+            cwd=cwd,
+            env=env,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+        )
+
+        stdout_chunks: list[str] = []
+        stderr_chunks: list[str] = []
+        state_lock = threading.Lock()
+        start_time = time.monotonic()
+        last_activity = start_time
+        seen_output = False
+        last_stderr = ""
+
+        def record_activity(chunk: str, *, is_stderr: bool) -> None:
+            nonlocal last_activity, seen_output, last_stderr
+            if not chunk:
+                return
+            with state_lock:
+                last_activity = time.monotonic()
+                seen_output = True
+                if is_stderr and chunk.strip():
+                    last_stderr = chunk.strip()
+
+        def read_stream(stream, chunks: list[str], *, is_stderr: bool) -> None:
+            try:
+                for line in iter(stream.readline, ""):
+                    chunks.append(line)
+                    record_activity(line, is_stderr=is_stderr)
+            finally:
+                stream.close()
+
+        stdout_thread = threading.Thread(
+            target=read_stream,
+            args=(proc.stdout, stdout_chunks),
+            kwargs={"is_stderr": False},
+            daemon=True,
+        )
+        stderr_thread = threading.Thread(
+            target=read_stream,
+            args=(proc.stderr, stderr_chunks),
+            kwargs={"is_stderr": True},
+            daemon=True,
+        )
+        stdout_thread.start()
+        stderr_thread.start()
+
+        stall_reported = False
+        while proc.poll() is None:
+            if on_stall and not stall_reported:
+                now = time.monotonic()
+                with state_lock:
+                    idle_seconds = now - last_activity
+                    seen_output_snapshot = seen_output
+                    last_stderr_snapshot = last_stderr
+                if idle_seconds >= self.STALL_WARNING_AFTER_SECONDS:
+                    stall_reported = True
+                    info = AgentStallInfo(
+                        command=tuple(args),
+                        elapsed_seconds=now - start_time,
+                        idle_seconds=idle_seconds,
+                        seen_output=seen_output_snapshot,
+                        last_stderr=last_stderr_snapshot,
+                    )
+                    logger.warning(
+                        "Agent command appears stalled after %.1fs without output: %s",
+                        info.idle_seconds,
+                        " ".join(args[:3]),
+                    )
+                    try:
+                        on_stall(info)
+                    except Exception:
+                        logger.exception("Agent stall callback failed.")
+            time.sleep(self.STALL_POLL_INTERVAL_SECONDS)
+
+        stdout_thread.join()
+        stderr_thread.join()
+        stdout = "".join(stdout_chunks)
+        stderr = "".join(stderr_chunks)
+        session_id, parsed_success, assistant_text, error_message, events = self._parse_jsonl(stdout)
+
+        success = proc.returncode == 0 and parsed_success
+        if not success and not error_message:
+            error_message = stderr.strip() or "Agent command failed."
+
+        return AgentRunResult(
+            session_id=session_id,
+            success=success,
+            assistant_text=assistant_text,
+            error_message=error_message,
+            raw_events=events,
+        )
+
+    def _run_with_output_file(
+        self,
+        args: list[str],
+        *,
+        cwd: Path,
+        tail_args: int,
+        env: Optional[dict[str, str]] = None,
+        on_stall: Optional[Callable[[AgentStallInfo], None]] = None,
+    ) -> AgentRunResult:
+        with tempfile.NamedTemporaryFile(prefix="coding-agent-telegram-", suffix=".txt", delete=False) as handle:
+            output_path = Path(handle.name)
+
+        try:
+            split_at = len(args) - tail_args
+            result = self._run(
+                [*args[:split_at], "--output-last-message", str(output_path), *args[split_at:]],
+                cwd=cwd,
+                env=env,
+                on_stall=on_stall,
+            )
+            if output_path.exists():
+                output_text = output_path.read_text(encoding="utf-8").strip()
+                if output_text:
+                    result.assistant_text = output_text
+            return result
+        finally:
+            try:
+                os.unlink(output_path)
+            except FileNotFoundError:
+                pass
+
+    def _codex_base(
+        self,
+        project_path: Path,
+        user_message: str,
+        skip_git_repo_check: bool,
+        image_paths: Sequence[Path] = (),
+    ) -> list[str]:
+        args = []
+        if self.codex_model:
+            args.extend(["-m", self.codex_model])
+        for image_path in image_paths:
+            args.extend(["--image", str(image_path)])
+        args.extend(
+            [
+            "-c",
+            f"approval_policy={self.approval_policy}",
+            "-c",
+            f"sandbox_mode={self.sandbox_mode}",
+            "--json",
+            "--cd",
+            str(project_path),
+            f"{self.PROMPT_PREFIX}{user_message}",
+            ]
+        )
+        if skip_git_repo_check:
+            return ["--skip-git-repo-check", *args]
+        return args
+
+    def _codex_resume_base(
+        self,
+        user_message: str,
+        skip_git_repo_check: bool,
+        image_paths: Sequence[Path] = (),
+    ) -> list[str]:
+        args = []
+        if self.codex_model:
+            args.extend(["-m", self.codex_model])
+        for image_path in image_paths:
+            args.extend(["--image", str(image_path)])
+        args.extend(
+            [
+                "-c",
+                f"approval_policy={self.approval_policy}",
+                "-c",
+                f"sandbox_mode={self.sandbox_mode}",
+                "--json",
+                f"{self.PROMPT_PREFIX}{user_message}",
+            ]
+        )
+        if skip_git_repo_check:
+            return ["--skip-git-repo-check", *args]
+        return args
+
+    def _codex_resume_args(
+        self,
+        session_id: str,
+        user_message: str,
+        skip_git_repo_check: bool,
+        image_paths: Sequence[Path] = (),
+    ) -> list[str]:
+        return [
+            *self._codex_resume_base(user_message, skip_git_repo_check, image_paths)[:-1],
+            session_id,
+            f"{self.PROMPT_PREFIX}{user_message}",
+        ]
+
+    def _copilot_env(self, project_path: Path, skip_git_repo_check: bool) -> dict[str, str]:
+        env = os.environ.copy()
+        if skip_git_repo_check:
+            env["COPILOT_HOME"] = str(project_path / ".copilot")
+        return env
+
+    def _copilot_base(self, user_message: str, skip_git_repo_check: bool) -> list[str]:
+        args = []
+        if self.copilot_model:
+            args.extend(["--model", self.copilot_model])
+        if self.copilot_autopilot:
+            args.append("--autopilot")
+        if self.copilot_no_ask_user:
+            args.append("--no-ask-user")
+        if self.copilot_allow_all:
+            args.append("--allow-all")
+        elif self.copilot_allow_all_tools or skip_git_repo_check:
+            args.append("--allow-all-tools")
+        for tool in self.copilot_allow_tools:
+            args.extend(["--allow-tool", tool])
+        for tool in self.copilot_deny_tools:
+            args.extend(["--deny-tool", tool])
+        if self.copilot_available_tools:
+            args.extend(["--available-tools", ",".join(self.copilot_available_tools)])
+        args.extend(
+            [
+            "--output-format=json",
+            "--prompt",
+            f"{self.PROMPT_PREFIX}{user_message}",
+            ]
+        )
+        return args
+
+    def create_session(
+        self,
+        provider: str,
+        project_path: Path,
+        user_message: str,
+        *,
+        skip_git_repo_check: bool = False,
+        image_paths: Sequence[Path] = (),
+        on_stall: Optional[Callable[[AgentStallInfo], None]] = None,
+    ) -> AgentRunResult:
+        if provider == "codex":
+            args = [
+                self.codex_bin,
+                "exec",
+                *self._codex_base(project_path, user_message, skip_git_repo_check, image_paths),
+            ]
+            return self._run_with_output_file(args, cwd=project_path, tail_args=1, on_stall=on_stall)
+        elif provider == "copilot":
+            if image_paths:
+                return AgentRunResult(None, False, "", "Image attachments are not supported for Copilot sessions.", [])
+            args = [self.copilot_bin, *self._copilot_base(user_message, skip_git_repo_check)]
+            return self._run(
+                args,
+                cwd=project_path,
+                env=self._copilot_env(project_path, skip_git_repo_check),
+                on_stall=on_stall,
+            )
+        else:
+            return AgentRunResult(None, False, "", f"Unsupported provider: {provider}", [])
+
+    def resume_session(
+        self,
+        provider: str,
+        session_id: str,
+        project_path: Path,
+        user_message: str,
+        *,
+        skip_git_repo_check: bool = False,
+        image_paths: Sequence[Path] = (),
+        on_stall: Optional[Callable[[AgentStallInfo], None]] = None,
+    ) -> AgentRunResult:
+        if provider == "codex":
+            args = [
+                self.codex_bin,
+                "exec",
+                "resume",
+                *self._codex_resume_args(session_id, user_message, skip_git_repo_check, image_paths),
+            ]
+            return self._run_with_output_file(args, cwd=project_path, tail_args=2, on_stall=on_stall)
+        elif provider == "copilot":
+            if image_paths:
+                return AgentRunResult(None, False, "", "Image attachments are not supported for Copilot sessions.", [])
+            args = [self.copilot_bin, f"--resume={session_id}", *self._copilot_base(user_message, skip_git_repo_check)]
+            return self._run(
+                args,
+                cwd=project_path,
+                env=self._copilot_env(project_path, skip_git_repo_check),
+                on_stall=on_stall,
+            )
+        else:
+            return AgentRunResult(None, False, "", f"Unsupported provider: {provider}", [])

coding_agent_telegram/bot.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import logging
+
+from telegram import BotCommand, BotCommandScopeChat, BotCommandScopeDefault
+from telegram.ext import Application, CallbackQueryHandler, CommandHandler, MessageHandler, filters as tg_filters
+
+from coding_agent_telegram.command_router import CommandRouter
+
+
+logger = logging.getLogger(__name__)
+
+
+def default_bot_commands(*, enable_commit_command: bool) -> list[BotCommand]:
+    commands = [
+        BotCommand("project", "Set the current project folder"),
+        BotCommand("branch", "Create and switch to a git work branch"),
+        BotCommand("new", "Create a new session"),
+        BotCommand("switch", "List sessions or switch to one"),
+        BotCommand("current", "Show the active session"),
+        BotCommand("push", "Push the current session branch"),
+    ]
+    if enable_commit_command:
+        commands.insert(5, BotCommand("commit", "Run validated git commit commands"))
+    return commands
+
+
+def allowed_private_chat_filter(allowed_chat_ids: set[int]):
+    return tg_filters.Chat(chat_id=sorted(allowed_chat_ids)) & tg_filters.ChatType.PRIVATE
+
+
+async def initialize_bot_commands(app: Application, *, enable_commit_command: bool, allowed_chat_ids: set[int]) -> None:
+    commands = default_bot_commands(enable_commit_command=enable_commit_command)
+    await app.bot.delete_my_commands(scope=BotCommandScopeDefault())
+    for chat_id in sorted(allowed_chat_ids):
+        await app.bot.set_my_commands(commands, scope=BotCommandScopeChat(chat_id))
+
+
+async def handle_error(update, context) -> None:
+    logger.exception("Telegram handler failed.", exc_info=context.error)
+    if update is not None and getattr(update, "effective_chat", None) is not None:
+        await context.bot.send_message(
+            chat_id=update.effective_chat.id,
+            text="⚠️ Command failed. Check the server log for details.",
+        )
+
+
+def build_application(token: str, router: CommandRouter, *, allowed_chat_ids: set[int]) -> Application:
+    app = Application.builder().token(token).build()
+    allowed_private = allowed_private_chat_filter(allowed_chat_ids)
+    unsupported_media = (
+        tg_filters.ANIMATION
+        | tg_filters.AUDIO
+        | tg_filters.Document.ALL
+        | tg_filters.Sticker.ALL
+        | tg_filters.VIDEO
+        | tg_filters.VIDEO_NOTE
+        | tg_filters.VOICE
+    )
+
+    app.add_handler(CommandHandler("project", router.handle_project, filters=allowed_private))
+    app.add_handler(CommandHandler("branch", router.handle_branch, filters=allowed_private))
+    app.add_handler(CommandHandler("new", router.handle_new, filters=allowed_private))
+    app.add_handler(CommandHandler("switch", router.handle_switch, filters=allowed_private))
+    app.add_handler(CommandHandler("current", router.handle_current, filters=allowed_private))
+    app.add_handler(CommandHandler("commit", router.handle_commit, filters=allowed_private))
+    app.add_handler(CommandHandler("push", router.handle_push, filters=allowed_private))
+    app.add_handler(CallbackQueryHandler(router.handle_trust_project_callback, pattern=r"^trustproject:(yes|no):"))
+    app.add_handler(MessageHandler(allowed_private & tg_filters.PHOTO, router.handle_photo))
+    app.add_handler(MessageHandler(allowed_private & tg_filters.TEXT & ~tg_filters.COMMAND, router.handle_message))
+    app.add_handler(MessageHandler(allowed_private & unsupported_media, router.handle_unsupported_message))
+    app.add_error_handler(handle_error)
+
+    return app

coding_agent_telegram/cli.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import importlib.resources
+import logging
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from coding_agent_telegram.agent_runner import MultiAgentRunner
+from coding_agent_telegram.bot import build_application, default_bot_commands, initialize_bot_commands
+from coding_agent_telegram.command_router import CommandRouter, RouterDeps
+from coding_agent_telegram.config import load_config
+from coding_agent_telegram.logging_utils import setup_logging
+from coding_agent_telegram.session_store import SessionStore
+
+
+logger = logging.getLogger(__name__)
+BOT_ID_HASH_PREFIX_LENGTH = 12
+
+
+def _ensure_env_file() -> Path:
+    env_path = Path.cwd() / ".env"
+    if not env_path.exists():
+        template = importlib.resources.files("coding_agent_telegram").joinpath("resources/.env.example").read_text(
+            encoding="utf-8"
+        )
+        env_path.write_text(template, encoding="utf-8")
+    return env_path
+
+
+def _bot_id_from_token(token: str) -> str:
+    return f"bot-{hashlib.sha256(token.encode('utf-8')).hexdigest()[:BOT_ID_HASH_PREFIX_LENGTH]}"
+
+
+async def _run_polling_apps(apps: Sequence) -> None:
+    started_apps = []
+    try:
+        for app in apps:
+            await app.initialize()
+            me = await app.bot.get_me()
+            logger.info(
+                "Connected Telegram bot: @%s (id=%s, name=%s)",
+                me.username or "unknown",
+                me.id,
+                me.first_name,
+            )
+            enable_commit_command = bool(app.bot_data.get("enable_commit_command", False))
+            allowed_chat_ids = set(app.bot_data.get("allowed_chat_ids", set()))
+            await initialize_bot_commands(
+                app,
+                enable_commit_command=enable_commit_command,
+                allowed_chat_ids=allowed_chat_ids,
+            )
+            logger.info(
+                "Registered %d Telegram commands for %d allowed chat(s) on @%s",
+                len(default_bot_commands(enable_commit_command=enable_commit_command)),
+                len(allowed_chat_ids),
+                me.username or "unknown",
+            )
+            await app.start()
+            if app.updater is None:
+                raise RuntimeError("Telegram updater is not available.")
+            await app.updater.start_polling()
+            logger.info("Started polling for @%s", me.username or "unknown")
+            started_apps.append(app)
+
+        logger.info("Started %d Telegram bot(s).", len(started_apps))
+        await asyncio.Event().wait()
+    finally:
+        for app in reversed(started_apps):
+            if app.updater is not None:
+                await app.updater.stop()
+            await app.stop()
+            await app.shutdown()
+
+
+async def _run(cfg, store: SessionStore, runner: MultiAgentRunner) -> None:
+    apps = []
+    for token in cfg.telegram_bot_tokens:
+        router = CommandRouter(RouterDeps(cfg=cfg, store=store, agent_runner=runner, bot_id=_bot_id_from_token(token)))
+        app = build_application(token, router, allowed_chat_ids=cfg.allowed_chat_ids)
+        app.bot_data["enable_commit_command"] = cfg.enable_commit_command
+        app.bot_data["allowed_chat_ids"] = set(cfg.allowed_chat_ids)
+        apps.append(app)
+
+    await _run_polling_apps(apps)
+
+
+def main() -> None:
+    try:
+        cfg = load_config()
+    except ValueError as exc:
+        env_path = _ensure_env_file()
+        print(str(exc), file=sys.stderr)
+        print("", file=sys.stderr)
+        print(f"Created {env_path} if it did not already exist.", file=sys.stderr)
+        print("Update these fields in .env:", file=sys.stderr)
+        print("- WORKSPACE_ROOT", file=sys.stderr)
+        print("- TELEGRAM_BOT_TOKENS", file=sys.stderr)
+        print("- ALLOWED_CHAT_IDS", file=sys.stderr)
+        print("- LOG_DIR", file=sys.stderr)
+        print("", file=sys.stderr)
+        print("Then run: coding-agent-telegram", file=sys.stderr)
+        raise SystemExit(1)
+
+    log_file = setup_logging(cfg.log_level, cfg.log_dir)
+    logger.info("Logging to %s", log_file)
+
+    store = SessionStore(cfg.state_file, cfg.state_backup_file)
+    runner = MultiAgentRunner(
+        codex_bin=cfg.codex_bin,
+        copilot_bin=cfg.copilot_bin,
+        approval_policy=cfg.codex_approval_policy,
+        sandbox_mode=cfg.codex_sandbox_mode,
+        codex_model=cfg.codex_model,
+        copilot_model=cfg.copilot_model,
+        copilot_autopilot=cfg.copilot_autopilot,
+        copilot_no_ask_user=cfg.copilot_no_ask_user,
+        copilot_allow_all=cfg.copilot_allow_all,
+        copilot_allow_all_tools=cfg.copilot_allow_all_tools,
+        copilot_allow_tools=cfg.copilot_allow_tools,
+        copilot_deny_tools=cfg.copilot_deny_tools,
+        copilot_available_tools=cfg.copilot_available_tools,
+    )
+    try:
+        asyncio.run(_run(cfg, store, runner))
+    except KeyboardInterrupt:
+        logger.info("Stopping Telegram bot polling.")

coding_agent_telegram/command_router.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from coding_agent_telegram.router.base import CommandRouterBase, RouterDeps
+from coding_agent_telegram.router.git_commands import GitCommandMixin
+from coding_agent_telegram.router.message_commands import MessageCommandMixin
+from coding_agent_telegram.router.project_commands import ProjectCommandMixin
+from coding_agent_telegram.router.session_commands import SessionCommandMixin
+
+
+class CommandRouter(
+    ProjectCommandMixin,
+    GitCommandMixin,
+    SessionCommandMixin,
+    MessageCommandMixin,
+    CommandRouterBase,
+):
+    """Compose categorized command handlers behind the historical router API."""
+