ctrlrelay 0.10.0__py3-none-any.whl

ctrlrelay/templates/launchd/bridge.plist.template

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${LABEL_PREFIX}.ctrlrelay-bridge</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${CTRLRELAY_BIN}</string>
+        <string>bridge</string>
+        <string>start</string>
+        <string>--foreground</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>CTRLRELAY_TELEGRAM_TOKEN</key>
+        <string>${CTRLRELAY_TELEGRAM_TOKEN}</string>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+        <!-- Without PYTHONUNBUFFERED, ctrlrelay's stdout sits in Python's
+             stdio buffer instead of flushing line-by-line, making
+             `tail -f ~/.ctrlrelay/logs/bridge.log` lag noticeably. -->
+        <key>PYTHONUNBUFFERED</key>
+        <string>1</string>
+    </dict>
+    <key>WorkingDirectory</key>
+    <string>${WORKDIR}</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>${HOME}/.ctrlrelay/logs/bridge.log</string>
+    <key>StandardErrorPath</key>
+    <string>${HOME}/.ctrlrelay/logs/bridge.error.log</string>
+</dict>
+</plist>

ctrlrelay/templates/launchd/poller.plist.template

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${LABEL_PREFIX}.ctrlrelay-poller</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${CTRLRELAY_BIN}</string>
+        <string>poller</string>
+        <string>start</string>
+        <string>--foreground</string>
+        <string>--interval</string>
+        <string>${POLLER_INTERVAL}</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>CTRLRELAY_TELEGRAM_TOKEN</key>
+        <string>${CTRLRELAY_TELEGRAM_TOKEN}</string>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+        <!-- Without PYTHONUNBUFFERED, ctrlrelay's stdout sits in Python's
+             stdio buffer instead of flushing line-by-line, making
+             `tail -f ~/.ctrlrelay/logs/poller.log` lag noticeably. -->
+        <key>PYTHONUNBUFFERED</key>
+        <string>1</string>
+    </dict>
+    <key>WorkingDirectory</key>
+    <string>${WORKDIR}</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <!-- Give the in-process scheduler time to drain a running secops
+         sweep on stop (worktree cleanup can take ~120s). launchd's
+         default ExitTimeOut is 20s, which would SIGKILL mid-cleanup. -->
+    <key>ExitTimeOut</key>
+    <integer>180</integer>
+    <key>StandardOutPath</key>
+    <string>${HOME}/.ctrlrelay/logs/poller.log</string>
+    <key>StandardErrorPath</key>
+    <string>${HOME}/.ctrlrelay/logs/poller.error.log</string>
+</dict>
+</plist>

ctrlrelay/templates/systemd/bridge.service.template

@@ -0,0 +1,20 @@
+[Unit]
+Description=ctrlrelay Telegram bridge
+After=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=${WORKDIR}
+Environment=CTRLRELAY_TELEGRAM_TOKEN=${CTRLRELAY_TELEGRAM_TOKEN}
+# Without PYTHONUNBUFFERED, ctrlrelay's stdout sits in Python's stdio
+# buffer instead of flushing line-by-line, making `tail -f` and
+# `journalctl -f` lag noticeably.
+Environment=PYTHONUNBUFFERED=1
+ExecStart=${CTRLRELAY_BIN} bridge start --foreground
+Restart=always
+RestartSec=5
+StandardOutput=append:%h/.ctrlrelay/logs/bridge.log
+StandardError=append:%h/.ctrlrelay/logs/bridge.error.log
+
+[Install]
+WantedBy=default.target

ctrlrelay/templates/systemd/poller.service.template

@@ -0,0 +1,25 @@
+[Unit]
+Description=ctrlrelay issue poller
+After=network-online.target ctrlrelay-bridge.service
+
+[Service]
+Type=simple
+WorkingDirectory=${WORKDIR}
+Environment=CTRLRELAY_TELEGRAM_TOKEN=${CTRLRELAY_TELEGRAM_TOKEN}
+# Without PYTHONUNBUFFERED, ctrlrelay's stdout sits in Python's stdio
+# buffer instead of flushing line-by-line, making `tail -f` and
+# `journalctl -f` lag noticeably.
+Environment=PYTHONUNBUFFERED=1
+ExecStart=${CTRLRELAY_BIN} poller start --foreground --interval ${POLLER_INTERVAL}
+Restart=always
+RestartSec=5
+# Give the in-process scheduler time to drain a running secops sweep
+# on stop (worktree cleanup can take ~120s). systemd's default
+# TimeoutStopSec is 90s, which would SIGKILL the poller mid-cleanup
+# and leak git worktree admin state.
+TimeoutStopSec=180
+StandardOutput=append:%h/.ctrlrelay/logs/poller.log
+StandardError=append:%h/.ctrlrelay/logs/poller.error.log
+
+[Install]
+WantedBy=default.target

ctrlrelay/transports/__init__.py

@@ -0,0 +1,34 @@
+"""Transport abstraction for orchestrator communication."""
+
+from ctrlrelay.core.config import TransportConfig, TransportType
+from ctrlrelay.transports.base import Transport, TransportError
+from ctrlrelay.transports.file_mock import FileMockTransport
+from ctrlrelay.transports.socket_client import SocketTransport
+
+
+def get_transport(config: TransportConfig) -> Transport:
+    """Create transport instance from config."""
+    if config.type == TransportType.FILE_MOCK:
+        assert config.file_mock is not None
+        return FileMockTransport(
+            inbox=config.file_mock.inbox,
+            outbox=config.file_mock.outbox,
+        )
+
+    if config.type == TransportType.TELEGRAM:
+        assert config.telegram is not None
+        return SocketTransport(
+            socket_path=config.telegram.socket_path,
+            ask_timeout_seconds=config.telegram.ask_timeout_seconds,
+        )
+
+    raise TransportError(f"Unknown transport type: {config.type}")
+
+
+__all__ = [
+    "FileMockTransport",
+    "SocketTransport",
+    "Transport",
+    "TransportError",
+    "get_transport",
+]

ctrlrelay/transports/base.py

@@ -0,0 +1,74 @@
+"""Transport protocol definition."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+class TransportError(Exception):
+    """Raised when transport operations fail."""
+
+
+class TransportUnknownDeliveryError(TransportError):
+    """Raised when a request may or may not have been delivered.
+
+    Delivery is only ever *confirmed* by the far side's acknowledgement.
+    Everything else divides in two: we know the bytes never left (a
+    definite failure), or we do not (unknown). Enumerating individual
+    ambiguous cases does not converge — the honest discriminator is
+    whether anything was written at all.
+
+    Subclasses TransportError so existing handlers are unaffected.
+    """
+
+
+class TransportTimeoutError(TransportUnknownDeliveryError):
+    """Sent, but no reply arrived in time.
+
+    A specific unknown: the request went out and the far side may still
+    act on it after we stop waiting.
+    """
+
+
+@runtime_checkable
+class Transport(Protocol):
+    """Protocol for orchestrator-to-human communication.
+
+    Implementations accept optional correlation kwargs (``session_id``,
+    ``repo``, ``issue_number``) used solely for structured logging — they are
+    never part of the wire payload.
+    """
+
+    async def send(
+        self,
+        message: str,
+        *,
+        session_id: str | None = None,
+        repo: str | None = None,
+        issue_number: int | None = None,
+    ) -> None:
+        """Send a one-way message (no response expected)."""
+        ...
+
+    async def ask(
+        self,
+        question: str,
+        options: list[str] | None = None,
+        timeout: int | None = None,
+        *,
+        session_id: str | None = None,
+        repo: str | None = None,
+        issue_number: int | None = None,
+    ) -> str:
+        """Ask a question and wait for response.
+
+        ``timeout`` of ``None`` means "use the implementation's configured
+        default" — callers that have no opinion must not pin a literal here,
+        or the operator's ``ask_timeout_seconds`` setting is silently
+        bypassed.
+        """
+        ...
+
+    async def close(self) -> None:
+        """Close the transport connection."""
+        ...

ctrlrelay/transports/file_mock.py

@@ -0,0 +1,103 @@
+"""File-based mock transport for testing."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+from ctrlrelay.core.obs import get_logger, hash_text, log_event
+from ctrlrelay.transports.base import TransportError
+
+_logger = get_logger("transport.file_mock")
+
+
+class FileMockTransport:
+    """Transport that reads/writes to files for testing."""
+
+    def __init__(
+        self,
+        inbox: Path,
+        outbox: Path,
+        ask_timeout_seconds: int = 300,
+    ) -> None:
+        self.inbox = inbox
+        self.outbox = outbox
+        self.ask_timeout_seconds = ask_timeout_seconds
+
+    async def send(
+        self,
+        message: str,
+        *,
+        session_id: str | None = None,
+        repo: str | None = None,
+        issue_number: int | None = None,
+    ) -> None:
+        """Write message to outbox file."""
+        timestamp = datetime.now(timezone.utc).isoformat()
+        with self.outbox.open("a") as f:
+            f.write(f"[{timestamp}] {message}\n")
+
+    async def ask(
+        self,
+        question: str,
+        options: list[str] | None = None,
+        timeout: int | None = None,
+        *,
+        session_id: str | None = None,
+        repo: str | None = None,
+        issue_number: int | None = None,
+    ) -> str:
+        """Write question to outbox and poll inbox for answer."""
+        if timeout is None:
+            timeout = self.ask_timeout_seconds
+        timestamp = datetime.now(timezone.utc).isoformat()
+        opts = f" [{'/'.join(options)}]" if options else ""
+        with self.outbox.open("a") as f:
+            f.write(f"[{timestamp}] QUESTION: {question}{opts}\n")
+
+        # Logged only after the outbox write, and without the question text:
+        # hash + length are enough to correlate, and keep operator content
+        # out of the log stream.
+        log_event(
+            _logger,
+            "dev.question.posted",
+            session_id=session_id,
+            repo=repo,
+            issue_number=issue_number,
+            transport="file_mock",
+            destination=str(self.outbox),
+            question_length=len(question),
+            question_hash=hash_text(question),
+            options=options,
+        )
+
+        sent_at = time.monotonic()
+        start = asyncio.get_event_loop().time()
+        while True:
+            content = self.inbox.read_text().strip()
+            if content:
+                self.inbox.write_text("")
+                answer = content.split("\n")[0].strip()
+                log_event(
+                    _logger,
+                    "dev.answer.received",
+                    session_id=session_id,
+                    repo=repo,
+                    issue_number=issue_number,
+                    transport="file_mock",
+                    answer_length=len(answer),
+                    answer_hash=hash_text(answer),
+                    elapsed_ms=int((time.monotonic() - sent_at) * 1000),
+                )
+                return answer
+
+            if asyncio.get_event_loop().time() - start > timeout:
+                raise TransportError(f"ask() timeout after {timeout}s")
+
+            await asyncio.sleep(0.5)
+
+    async def close(self) -> None:
+        """No-op for file transport."""
+        pass

ctrlrelay/transports/socket_client.py

@@ -0,0 +1,298 @@
+"""Unix socket transport client for bridge communication."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+import uuid
+from collections.abc import Callable
+from pathlib import Path
+
+from ctrlrelay.bridge.protocol import (
+    BridgeMessage,
+    BridgeOp,
+    ProtocolError,
+    parse_message,
+    serialize_message,
+)
+from ctrlrelay.core.obs import get_logger, hash_text, log_event
+from ctrlrelay.transports.base import (
+    TransportError,
+    TransportTimeoutError,
+    TransportUnknownDeliveryError,
+)
+
+_logger = get_logger("transport.socket")
+
+
+class SocketTransport:
+    """Transport that connects to bridge via Unix socket."""
+
+    def __init__(
+        self,
+        socket_path: Path,
+        ask_timeout_seconds: int = 300,
+    ) -> None:
+        self.socket_path = socket_path
+        # Per-instance default for ask(). Callers construct this from
+        # ``transport.telegram.ask_timeout_seconds`` so a single operator
+        # setting governs every pipeline's BLOCKED wait; the 300s fallback
+        # only applies to ad-hoc construction in tests and one-shot CLI
+        # helpers that never ask.
+        self.ask_timeout_seconds = ask_timeout_seconds
+        self._reader: asyncio.StreamReader | None = None
+        self._writer: asyncio.StreamWriter | None = None
+        self._pending: dict[str, asyncio.Future[BridgeMessage]] = {}
+        self._on_ack: dict[str, Callable[[], None]] = {}
+        self._receive_task: asyncio.Task | None = None
+
+    @property
+    def connected(self) -> bool:
+        return self._writer is not None and not self._writer.is_closing()
+
+    async def connect(self) -> None:
+        """Connect to bridge socket."""
+        try:
+            self._reader, self._writer = await asyncio.open_unix_connection(
+                str(self.socket_path)
+            )
+            self._receive_task = asyncio.create_task(self._receive_loop())
+        except (OSError, ConnectionRefusedError) as e:
+            raise TransportError(f"Failed to connect to bridge: {e}") from e
+
+    async def _receive_loop(self) -> None:
+        """Background task to receive messages from bridge."""
+        assert self._reader is not None
+        try:
+            while True:
+                line = await self._reader.readline()
+                if not line:
+                    break
+                try:
+                    msg = parse_message(line.decode())
+                    if msg.request_id and msg.request_id in self._pending:
+                        # The bridge sends two messages back for an ASK:
+                        # an intermediate ACK(status="pending") immediately
+                        # after queuing for Telegram, then an ANSWER (or
+                        # ERROR) once the operator replies. Resolving the
+                        # future on the first ACK collapses the wait
+                        # prematurely — caller sees "Unexpected response:
+                        # BridgeOp.ACK" and throws. Skip those to keep
+                        # waiting. Terminal ACKs (status="sent" from SEND)
+                        # remain the final response and resolve normally.
+                        if msg.op == BridgeOp.ACK and msg.status == "pending":
+                            # This ACK is also the only proof the bridge got
+                            # the question in front of the operator, so it is
+                            # what "posted" is allowed to mean.
+                            callback = self._on_ack.get(msg.request_id)
+                            if callback is not None:
+                                callback()
+                            continue
+                        self._pending[msg.request_id].set_result(msg)
+                except ProtocolError:
+                    pass
+        except asyncio.CancelledError:
+            pass
+
+    async def _send_message(self, msg: BridgeMessage) -> None:
+        """Send message to bridge.
+
+        Raises ``TransportError`` while nothing has been written — a
+        definite non-delivery — and ``TransportUnknownDeliveryError``
+        once bytes may have reached the far side. `drain()` failing does
+        not mean the bridge never saw the request: `write()` has already
+        handed the data to the transport, so the ASK may well have been
+        received and acted on.
+        """
+        if not self.connected:
+            raise TransportError("Transport not connected")
+        assert self._writer is not None
+        data = serialize_message(msg).encode()
+        try:
+            self._writer.write(data)
+        except Exception as e:
+            raise TransportError(f"Write failed: {e}") from e
+        try:
+            await self._writer.drain()
+        except Exception as e:
+            raise TransportUnknownDeliveryError(f"Drain failed: {e}") from e
+
+    async def _send_and_wait(
+        self,
+        msg: BridgeMessage,
+        timeout: int,
+        *,
+        on_ack: Callable[[], None] | None = None,
+    ) -> BridgeMessage:
+        """Send message and wait for response.
+
+        ``on_ack`` fires from the receive loop when the bridge sends its
+        intermediate ACK — the point at which the request is known to have
+        been accepted, as opposed to merely written to the socket.
+        """
+        assert msg.request_id is not None
+        future: asyncio.Future[BridgeMessage] = asyncio.get_event_loop().create_future()
+        self._pending[msg.request_id] = future
+        if on_ack is not None:
+            self._on_ack[msg.request_id] = on_ack
+
+        try:
+            await self._send_message(msg)
+            return await asyncio.wait_for(future, timeout=timeout)
+        except asyncio.TimeoutError as e:
+            raise TransportTimeoutError("Timeout waiting for response") from e
+        finally:
+            self._pending.pop(msg.request_id, None)
+            self._on_ack.pop(msg.request_id, None)
+
+    async def send(
+        self,
+        message: str,
+        *,
+        session_id: str | None = None,
+        repo: str | None = None,
+        issue_number: int | None = None,
+    ) -> None:
+        """Send a one-way message."""
+        request_id = f"r-{uuid.uuid4().hex[:8]}"
+        msg = BridgeMessage(
+            op=BridgeOp.SEND,
+            request_id=request_id,
+            text=message,
+            session_id=session_id,
+            repo=repo,
+            issue_number=issue_number,
+        )
+        await self._send_message(msg)
+
+    async def ask(
+        self,
+        question: str,
+        options: list[str] | None = None,
+        timeout: int | None = None,
+        *,
+        session_id: str | None = None,
+        repo: str | None = None,
+        issue_number: int | None = None,
+    ) -> str:
+        """Ask a question and wait for response."""
+        if timeout is None:
+            timeout = self.ask_timeout_seconds
+        request_id = f"r-{uuid.uuid4().hex[:8]}"
+        msg = BridgeMessage(
+            op=BridgeOp.ASK,
+            request_id=request_id,
+            question=question,
+            options=options,
+            timeout=timeout,
+            session_id=session_id,
+            repo=repo,
+            issue_number=issue_number,
+        )
+
+        # The question itself never reaches the log stream: these records go
+        # to stdout and are captured into ~/.ctrlrelay/logs, where operator
+        # content would sit in plaintext with no retention policy. The hash
+        # is enough to correlate one question across poller and bridge.
+        common = {
+            "session_id": session_id,
+            "repo": repo,
+            "issue_number": issue_number,
+            "transport": "socket",
+            "destination": str(self.socket_path),
+            "request_id": request_id,
+            "question_length": len(question),
+            "question_hash": hash_text(question),
+            "options": options,
+        }
+
+        posted = False
+
+        def _mark_posted() -> None:
+            # Fired by the receive loop on the bridge's ACK, which is the
+            # first moment the question is known to have reached Telegram.
+            # Logging before the write would claim a delivery that a failed
+            # socket write or a Telegram outage never made.
+            nonlocal posted
+            posted = True
+            log_event(_logger, "dev.question.posted", **common)
+
+        sent_at = time.monotonic()
+        try:
+            response = await self._send_and_wait(msg, timeout, on_ack=_mark_posted)
+        except Exception as e:
+            if not posted:
+                # A timeout is not a failed delivery. The bridge ACKs only
+                # after Telegram has accepted the message, so a post slower
+                # than our wait leaves us timing out first and the bridge
+                # succeeding afterwards — logging "post_failed" there would
+                # contradict the bridge's own "posted", which is the same
+                # false-claim problem this change exists to remove, just
+                # pointing the other way.
+                # Only claim a definite failure when the request
+                # provably never left. Anything past the write is
+                # unknown: no ACK arrived, but the bridge may have
+                # received and acted on it regardless.
+                unknown = isinstance(e, TransportUnknownDeliveryError)
+                log_event(
+                    _logger,
+                    "dev.question.post_unknown"
+                    if unknown
+                    else "dev.question.post_failed",
+                    **common,
+                    reason=type(e).__name__ if unknown else "send_failed",
+                    error=str(e)[:200],
+                )
+            raise
+
+        if response.op == BridgeOp.ERROR:
+            if not posted:
+                # The bridge knows whether Telegram answered; we do not.
+                # Re-deriving it here is what produced contradictory
+                # pairs — post_unknown on the bridge, post_failed on the
+                # transport, same request_id.
+                bridge_unknown = response.error == "telegram_delivery_unknown"
+                log_event(
+                    _logger,
+                    "dev.question.post_unknown"
+                    if bridge_unknown
+                    else "dev.question.post_failed",
+                    **common,
+                    reason="bridge_error",
+                    error=str(response.message)[:200],
+                )
+            raise TransportError(f"Bridge error: {response.message}")
+        if response.op == BridgeOp.ANSWER and response.answer:
+            if not posted:
+                # An answer proves the question was posted even if the ACK
+                # never arrived (older bridge, or the ACK was lost).
+                _mark_posted()
+            log_event(
+                _logger,
+                "dev.answer.received",
+                session_id=session_id,
+                repo=repo,
+                issue_number=issue_number,
+                transport="socket",
+                request_id=request_id,
+                answer_length=len(response.answer),
+                answer_hash=hash_text(response.answer),
+                elapsed_ms=int((time.monotonic() - sent_at) * 1000),
+            )
+            return response.answer
+
+        raise TransportError(f"Unexpected response: {response.op}")
+
+    async def close(self) -> None:
+        """Close the connection."""
+        if self._receive_task:
+            self._receive_task.cancel()
+            try:
+                await self._receive_task
+            except asyncio.CancelledError:
+                pass
+        if self._writer:
+            self._writer.close()
+            await self._writer.wait_closed()
+        self._reader = None
+        self._writer = None