ctrlrelay 0.1.5__py3-none-any.whl

ctrlrelay/__init__.py

@@ -0,0 +1,8 @@
+"""ctrlrelay: Local-first orchestrator for Claude Code."""
+
+from ctrlrelay.core import checkpoint
+
+__version__ = "0.1.3"
+
+# Public API
+__all__ = ["__version__", "checkpoint"]

ctrlrelay/bridge/__init__.py

@@ -0,0 +1,21 @@
+"""Bridge process for Telegram communication."""
+
+from ctrlrelay.bridge.protocol import (
+    BridgeMessage,
+    BridgeOp,
+    ProtocolError,
+    parse_message,
+    serialize_message,
+)
+from ctrlrelay.bridge.server import BridgeServer
+from ctrlrelay.bridge.telegram_handler import TelegramHandler
+
+__all__ = [
+    "BridgeMessage",
+    "BridgeOp",
+    "BridgeServer",
+    "ProtocolError",
+    "TelegramHandler",
+    "parse_message",
+    "serialize_message",
+]

ctrlrelay/bridge/__main__.py

@@ -0,0 +1,69 @@
+"""Bridge process entry point for daemon mode."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import signal
+import sys
+from pathlib import Path
+
+from ctrlrelay.bridge.server import BridgeServer
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="ctrlrelay Telegram bridge")
+    parser.add_argument("--socket-path", required=True, help="Unix socket path")
+    parser.add_argument(
+        "--bot-token-env",
+        default="CTRLRELAY_TELEGRAM_TOKEN",
+        help="Environment variable holding the Telegram bot token",
+    )
+    parser.add_argument("--chat-id", type=int, required=True, help="Telegram chat ID")
+    args = parser.parse_args()
+
+    bot_token = os.environ.get(args.bot_token_env)
+    if not bot_token:
+        print(
+            f"error: bot token env var '{args.bot_token_env}' is unset",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+
+    socket_path = Path(args.socket_path)
+    server = BridgeServer(
+        socket_path=socket_path,
+        bot_token=bot_token,
+        chat_id=args.chat_id,
+    )
+
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+
+    async def _run_server() -> None:
+        # Wrap start() in a finally that awaits stop() so the loop can't
+        # close before _telegram.close() and the socket unlink complete.
+        try:
+            await server.start()
+        finally:
+            await server.stop()
+
+    main_task = loop.create_task(_run_server())
+
+    def handle_signal(sig: int) -> None:
+        main_task.cancel()
+
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        loop.add_signal_handler(sig, handle_signal, sig)
+
+    try:
+        loop.run_until_complete(main_task)
+    except asyncio.CancelledError:
+        pass
+    finally:
+        loop.close()
+
+
+if __name__ == "__main__":
+    main()

ctrlrelay/bridge/protocol.py

@@ -0,0 +1,75 @@
+"""Bridge protocol message types and serialization."""
+
+from __future__ import annotations
+
+import json
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class ProtocolError(Exception):
+    """Raised when protocol parsing fails."""
+
+
+class BridgeOp(str, Enum):
+    """Bridge operation types."""
+
+    SEND = "send"
+    ASK = "ask"
+    ACK = "ack"
+    ANSWER = "answer"
+    PING = "ping"
+    PONG = "pong"
+    ERROR = "error"
+
+
+class BridgeMessage(BaseModel):
+    """Message exchanged between orchestrator and bridge."""
+
+    op: BridgeOp
+    request_id: str | None = None
+
+    # send
+    text: str | None = None
+
+    # ask
+    question: str | None = None
+    options: list[str] | None = None
+    timeout: int | None = None
+
+    # ack
+    status: str | None = None
+
+    # answer
+    answer: str | None = None
+    answered_at: str | None = None
+
+    # error
+    error: str | None = None
+    message: str | None = None
+
+    # Correlation fields (optional; used for structured logging only).
+    session_id: str | None = None
+    repo: str | None = None
+    issue_number: int | None = None
+
+
+def serialize_message(msg: BridgeMessage) -> str:
+    """Serialize message to newline-delimited JSON."""
+    data = msg.model_dump(exclude_none=True)
+    return json.dumps(data) + "\n"
+
+
+def parse_message(line: str) -> BridgeMessage:
+    """Parse newline-delimited JSON to message."""
+    try:
+        data: dict[str, Any] = json.loads(line.strip())
+    except json.JSONDecodeError as e:
+        raise ProtocolError(f"Invalid JSON: {e}") from e
+
+    if "op" not in data:
+        raise ProtocolError("Missing 'op' field in message")
+
+    return BridgeMessage.model_validate(data)

ctrlrelay/bridge/server.py

@@ -0,0 +1,285 @@
+"""Bridge server for Telegram communication."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import stat
+from collections import OrderedDict
+from datetime import datetime, timezone
+from pathlib import Path
+
+from ctrlrelay.bridge.protocol import (
+    BridgeMessage,
+    BridgeOp,
+    ProtocolError,
+    parse_message,
+    serialize_message,
+)
+from ctrlrelay.bridge.telegram_handler import TelegramHandler
+from ctrlrelay.core.obs import get_logger, hash_text, log_event
+
+_logger = get_logger("bridge.server")
+_log = logging.getLogger(__name__)
+
+
+class _PendingQuestion:
+    """Question posted to Telegram, awaiting the operator's reply."""
+
+    __slots__ = ("request_id", "telegram_msg_id", "writer")
+
+    def __init__(
+        self,
+        request_id: str,
+        telegram_msg_id: int,
+        writer: asyncio.StreamWriter,
+    ) -> None:
+        self.request_id = request_id
+        self.telegram_msg_id = telegram_msg_id
+        self.writer = writer
+
+
+class BridgeServer:
+    """Unix socket server that bridges to Telegram — bidirectional.
+
+    Outbound: clients send SEND/ASK over the socket and we hit Telegram.
+    Inbound: we long-poll Telegram for messages; when a reply arrives it's
+    matched to the oldest outstanding ASK (or by reply_to_message_id if
+    available) and we push an ANSWER frame over that client's socket."""
+
+    def __init__(
+        self,
+        socket_path: Path,
+        bot_token: str,
+        chat_id: int,
+    ) -> None:
+        self.socket_path = socket_path
+        self.bot_token = bot_token
+        self.chat_id = chat_id
+        self._server: asyncio.Server | None = None
+        self._running = False
+        self._telegram: TelegramHandler | None = None
+        # Insertion-ordered so FIFO dispatch is deterministic.
+        self._pending_questions: OrderedDict[str, _PendingQuestion] = OrderedDict()
+        self._pending_lock = asyncio.Lock()
+
+    async def start(self) -> None:
+        """Start the bridge server."""
+        self._telegram = TelegramHandler(
+            bot_token=self.bot_token,
+            chat_id=self.chat_id,
+        )
+        await self._telegram.start_polling(self._on_telegram_reply)
+
+        if self.socket_path.exists():
+            self.socket_path.unlink()
+
+        self.socket_path.parent.mkdir(parents=True, exist_ok=True)
+
+        self._server = await asyncio.start_unix_server(
+            self._handle_client,
+            path=str(self.socket_path),
+        )
+
+        os.chmod(self.socket_path, stat.S_IRUSR | stat.S_IWUSR)
+
+        self._running = True
+        async with self._server:
+            await self._server.serve_forever()
+
+    async def stop(self) -> None:
+        """Stop the bridge server."""
+        self._running = False
+        if self._server:
+            self._server.close()
+            await self._server.wait_closed()
+
+        if self._telegram:
+            await self._telegram.close()
+
+        if self.socket_path.exists():
+            self.socket_path.unlink()
+
+    async def _handle_client(
+        self,
+        reader: asyncio.StreamReader,
+        writer: asyncio.StreamWriter,
+    ) -> None:
+        """Handle a client connection."""
+        try:
+            while self._running:
+                line = await reader.readline()
+                if not line:
+                    break
+
+                try:
+                    msg = parse_message(line.decode())
+                except ProtocolError:
+                    continue
+
+                response = await self._handle_message(msg, writer)
+                if response is None:
+                    continue
+
+                # Response write races client disconnect: the transport
+                # (SocketTransport) finishes a send/ask round-trip and closes
+                # the socket while we're still flushing the ACK. Swallow the
+                # expected disconnect errors instead of propagating a
+                # traceback into bridge.error.log.
+                if writer.is_closing():
+                    break
+                try:
+                    writer.write(serialize_message(response).encode())
+                    await writer.drain()
+                except (ConnectionResetError, BrokenPipeError, OSError) as e:
+                    _log.debug(
+                        "bridge: client disconnected mid-response "
+                        "(op=%s request_id=%s err=%s)",
+                        msg.op, msg.request_id, e,
+                    )
+                    break
+        finally:
+            # Client disconnected — drop any outstanding questions tied to
+            # this writer so we don't try to answer a dead socket later.
+            async with self._pending_lock:
+                dead = [
+                    rid for rid, q in self._pending_questions.items()
+                    if q.writer is writer
+                ]
+                for rid in dead:
+                    self._pending_questions.pop(rid, None)
+            writer.close()
+            try:
+                await writer.wait_closed()
+            except Exception:
+                pass
+
+    async def _handle_message(
+        self,
+        msg: BridgeMessage,
+        writer: asyncio.StreamWriter,
+    ) -> BridgeMessage | None:
+        """Handle a single message and return response."""
+        if msg.op == BridgeOp.PING:
+            return BridgeMessage(op=BridgeOp.PONG)
+
+        if msg.op == BridgeOp.SEND:
+            try:
+                assert self._telegram is not None
+                await self._telegram.send(msg.text or "")
+                _log.info("bridge: SEND delivered, request_id=%s", msg.request_id)
+                return BridgeMessage(op=BridgeOp.ACK, request_id=msg.request_id, status="sent")
+            except Exception as e:
+                _log.warning("bridge: SEND failed, request_id=%s err=%s", msg.request_id, e)
+                return BridgeMessage(
+                    op=BridgeOp.ERROR,
+                    request_id=msg.request_id,
+                    error="telegram_api_error",
+                    message=str(e),
+                )
+
+        if msg.op == BridgeOp.ASK:
+            try:
+                assert self._telegram is not None
+                question = msg.question or ""
+                log_event(
+                    _logger,
+                    "dev.question.posted",
+                    session_id=msg.session_id,
+                    repo=msg.repo,
+                    issue_number=msg.issue_number,
+                    transport="telegram",
+                    destination=f"telegram:chat={self.chat_id}",
+                    request_id=msg.request_id,
+                    question=question,
+                    question_length=len(question),
+                    question_hash=hash_text(question),
+                    options=msg.options,
+                )
+                telegram_msg_id = await self._telegram.ask(
+                    question, options=msg.options
+                )
+                if msg.request_id:
+                    async with self._pending_lock:
+                        self._pending_questions[msg.request_id] = _PendingQuestion(
+                            request_id=msg.request_id,
+                            telegram_msg_id=telegram_msg_id,
+                            writer=writer,
+                        )
+                _log.info(
+                    "bridge: ASK posted request_id=%s telegram_msg_id=%s",
+                    msg.request_id, telegram_msg_id,
+                )
+                return BridgeMessage(
+                    op=BridgeOp.ACK, request_id=msg.request_id, status="pending",
+                )
+            except Exception as e:
+                _log.warning("bridge: ASK failed, request_id=%s err=%s", msg.request_id, e)
+                return BridgeMessage(
+                    op=BridgeOp.ERROR,
+                    request_id=msg.request_id,
+                    error="telegram_api_error",
+                    message=str(e),
+                )
+
+        return None
+
+    async def _on_telegram_reply(
+        self,
+        text: str,
+        reply_to_message_id: int | None,
+    ) -> None:
+        """Route an incoming Telegram message to the matching pending question.
+
+        Priority: if reply_to_message_id matches a tracked question, use it.
+        Otherwise fall back to FIFO (oldest outstanding question wins) —
+        good enough for the single-operator case."""
+        async with self._pending_lock:
+            match: _PendingQuestion | None = None
+            if reply_to_message_id is not None:
+                for q in self._pending_questions.values():
+                    if q.telegram_msg_id == reply_to_message_id:
+                        match = q
+                        break
+            if match is None and self._pending_questions:
+                # FIFO: pop oldest.
+                match = next(iter(self._pending_questions.values()))
+            if match is None:
+                _log.info(
+                    "bridge: incoming telegram msg with no pending question; "
+                    "text=%r", text[:80],
+                )
+                return
+            self._pending_questions.pop(match.request_id, None)
+
+        _log.info(
+            "bridge: delivering ANSWER request_id=%s len=%d",
+            match.request_id, len(text),
+        )
+        log_event(
+            _logger,
+            "dev.answer.received",
+            transport="telegram",
+            source=f"telegram:chat={self.chat_id}",
+            request_id=match.request_id,
+            telegram_msg_id=match.telegram_msg_id,
+            reply_to_message_id=reply_to_message_id,
+            answer=text,
+            answer_length=len(text),
+            answer_hash=hash_text(text),
+        )
+        answer = BridgeMessage(
+            op=BridgeOp.ANSWER,
+            request_id=match.request_id,
+            answer=text,
+            answered_at=datetime.now(timezone.utc).isoformat(),
+        )
+        try:
+            match.writer.write(serialize_message(answer).encode())
+            await match.writer.drain()
+        except Exception as e:
+            _log.warning(
+                "bridge: failed to deliver ANSWER request_id=%s err=%s",
+                match.request_id, e,
+            )

ctrlrelay/bridge/telegram_handler.py

@@ -0,0 +1,117 @@
+"""Telegram Bot API handler."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Awaitable, Callable
+
+from telegram import Bot, ReplyKeyboardMarkup, ReplyKeyboardRemove
+
+_log = logging.getLogger(__name__)
+
+IncomingMessageHandler = Callable[[str, int | None], Awaitable[None]]
+
+
+class TelegramHandler:
+    """Handles Telegram Bot API communication — outbound (send/ask) and
+    inbound (long-poll get_updates) for answers from the operator."""
+
+    def __init__(self, bot_token: str, chat_id: int) -> None:
+        self.bot = Bot(token=bot_token)
+        self.chat_id = chat_id
+        self._poll_task: asyncio.Task | None = None
+        self._offset: int = 0
+
+    async def send(self, text: str) -> int:
+        """Send a message to the configured chat."""
+        message = await self.bot.send_message(
+            chat_id=self.chat_id,
+            text=text,
+        )
+        return message.message_id
+
+    async def ask(
+        self,
+        question: str,
+        options: list[str] | None = None,
+    ) -> int:
+        """Send a question with optional reply keyboard."""
+        reply_markup = None
+        if options:
+            keyboard = [[opt] for opt in options]
+            reply_markup = ReplyKeyboardMarkup(
+                keyboard,
+                one_time_keyboard=True,
+                resize_keyboard=True,
+            )
+
+        message = await self.bot.send_message(
+            chat_id=self.chat_id,
+            text=question,
+            reply_markup=reply_markup or ReplyKeyboardRemove(),
+        )
+        return message.message_id
+
+    async def start_polling(self, handler: IncomingMessageHandler) -> None:
+        """Start long-polling Telegram for incoming messages from the
+        configured chat. For each message, invokes
+        ``handler(text, reply_to_message_id)`` where reply_to_message_id is
+        the id of the question the user replied to (or None for a fresh
+        message). Idempotent — a second call replaces the running loop."""
+        if self._poll_task is not None and not self._poll_task.done():
+            return
+        self._poll_task = asyncio.create_task(self._poll_loop(handler))
+
+    async def stop_polling(self) -> None:
+        """Stop the polling loop if running."""
+        if self._poll_task is None:
+            return
+        self._poll_task.cancel()
+        try:
+            await self._poll_task
+        except asyncio.CancelledError:
+            pass
+        self._poll_task = None
+
+    async def _poll_loop(self, handler: IncomingMessageHandler) -> None:
+        """Long-poll get_updates and forward messages from the configured chat."""
+        while True:
+            try:
+                updates = await self.bot.get_updates(
+                    offset=self._offset,
+                    timeout=30,
+                    allowed_updates=["message"],
+                )
+            except asyncio.CancelledError:
+                raise
+            except Exception as e:
+                # Transient network / auth error. Back off and keep trying.
+                _log.warning("telegram get_updates failed: %s", e)
+                await asyncio.sleep(5)
+                continue
+
+            for update in updates:
+                self._offset = update.update_id + 1
+                msg = update.message
+                if msg is None or msg.chat is None:
+                    continue
+                if msg.chat.id != self.chat_id:
+                    continue  # ignore messages from other chats
+                text = (msg.text or "").strip()
+                if not text:
+                    continue
+                reply_id = (
+                    msg.reply_to_message.message_id
+                    if msg.reply_to_message is not None
+                    else None
+                )
+                try:
+                    await handler(text, reply_id)
+                except Exception as e:
+                    _log.warning("bridge answer handler raised: %s", e)
+
+    async def close(self) -> None:
+        """Close the bot session."""
+        await self.stop_polling()
+        await self.bot.close()