ctrlrelay 0.10.0__py3-none-any.whl

ctrlrelay/__init__.py

@@ -0,0 +1,33 @@
+"""ctrlrelay: Local-first orchestrator for headless coding agents."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from ctrlrelay.core import checkpoint
+
+
+def _resolve_version() -> str:
+    try:
+        return version("ctrlrelay")
+    except PackageNotFoundError:
+        # Source checkout with no installed dist-info — e.g. a bare
+        # `pytest tests/` with pyproject's `pythonpath = ["src"]` as the
+        # only mechanism putting the package on sys.path. Fall back to
+        # parsing pyproject.toml so the drift-catcher test still sees a
+        # real version instead of a placeholder.
+        import tomllib
+        from pathlib import Path
+
+        pyproject = Path(__file__).resolve().parents[2] / "pyproject.toml"
+        if pyproject.is_file():
+            try:
+                with pyproject.open("rb") as f:
+                    return tomllib.load(f)["project"]["version"]
+            except (OSError, KeyError, tomllib.TOMLDecodeError):
+                pass
+        return "0.0.0+unknown"
+
+
+__version__ = _resolve_version()
+
+# 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,89 @@
+"""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")
+    parser.add_argument(
+        "--state-db",
+        default=None,
+        help=(
+            "Path to the orchestrator state.db. When provided, orphan "
+            "Telegram replies route to persisted BLOCKED sessions in "
+            "pending_resumes. Required for the resume-via-Telegram flow."
+        ),
+    )
+    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)
+
+    state_db = None
+    if args.state_db:
+        from ctrlrelay.core.state import StateDB
+        state_db = StateDB(Path(args.state_db))
+
+    socket_path = Path(args.socket_path)
+    server = BridgeServer(
+        socket_path=socket_path,
+        bot_token=bot_token,
+        chat_id=args.chat_id,
+        state_db=state_db,
+    )
+
+    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 state_db is not None:
+            try:
+                state_db.close()
+            except Exception:
+                pass
+
+
+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)