codex-telegram-bridge 0.5.3__py3-none-any.whl

agent_runtime/__init__.py

@@ -0,0 +1,17 @@
+"""Shared runtime contracts for Telegram-controlled Codex sessions."""
+
+from .approvals import ApprovalOption, ApprovalRequest
+from .capabilities import CapabilityRegistry, HeadCapabilities
+from .locks import WorkdirLock, WorkdirLockError
+from .types import AgentEvent, AgentMessage
+
+__all__ = [
+    "AgentEvent",
+    "AgentMessage",
+    "ApprovalOption",
+    "ApprovalRequest",
+    "CapabilityRegistry",
+    "HeadCapabilities",
+    "WorkdirLock",
+    "WorkdirLockError",
+]

agent_runtime/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""Head adapter implementations."""
+
+from .base import HeadAdapter
+from .codex_repl import CodexReplAdapter
+
+__all__ = ["CodexReplAdapter", "HeadAdapter"]

agent_runtime/adapters/base.py

@@ -0,0 +1,32 @@
+"""Protocol implemented by Codex runtime heads."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Protocol
+
+from agent_runtime.approvals import ApprovalOption
+from agent_runtime.capabilities import HeadCapabilities
+from agent_runtime.types import AgentEvent, AgentMessage
+
+
+class HeadAdapter(Protocol):
+    name: str
+
+    def spawn(self) -> None:
+        raise NotImplementedError
+
+    def send(self, message: AgentMessage) -> None:
+        raise NotImplementedError
+
+    def recv(self) -> Iterable[AgentEvent]:
+        raise NotImplementedError
+
+    def inject_approval(self, choice: ApprovalOption | str) -> None:
+        raise NotImplementedError
+
+    def kill(self) -> None:
+        raise NotImplementedError
+
+    def capabilities(self) -> HeadCapabilities:
+        raise NotImplementedError

agent_runtime/adapters/codex_repl.py

@@ -0,0 +1,109 @@
+"""Adapter for the visible Codex REPL controlled through tmux."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+from agent_runtime.approvals import ApprovalOption
+from agent_runtime.capabilities import HeadCapabilities
+from agent_runtime.types import AgentEvent, AgentMessage
+
+
+class CodexReplAdapter:
+    name = "codex_repl"
+
+    def __init__(self, repl: Any, workdir: Path | None = None) -> None:
+        self.repl = repl
+        self.workdir = workdir
+        self._session_path: Path | None = None
+        self._session_pos = 0
+
+    def spawn(self) -> None:
+        self.repl.verify()
+
+    def send(self, message: AgentMessage) -> None:
+        self.repl.paste_prompt(message.text)
+
+    def recv(self) -> Iterable[AgentEvent]:
+        path = self.session_file()
+        if path != self._session_path:
+            self._session_path = path
+            self._session_pos = 0
+
+        events: list[AgentEvent] = []
+        with path.open("r", encoding="utf-8", errors="replace") as handle:
+            handle.seek(self._session_pos)
+            while True:
+                line = handle.readline()
+                if not line:
+                    break
+                self._session_pos = handle.tell()
+                event = self._event_from_json_line(line)
+                if event:
+                    events.append(event)
+        return events
+
+    def inject_approval(self, choice: ApprovalOption | str) -> None:
+        key = choice.key if isinstance(choice, ApprovalOption) else str(choice)
+        self.repl.send_approval_key(key)
+
+    def kill(self) -> None:
+        return None
+
+    def capabilities(self) -> HeadCapabilities:
+        roots = (self.workdir,) if self.workdir else ()
+        return HeadCapabilities(
+            head=self.name,
+            vision=True,
+            audio=True,
+            video=True,
+            repl=True,
+            approval=True,
+            streaming=True,
+            workdir_access=roots,
+            notes=("visible Codex TUI via tmux", "final answers read from Codex JSONL"),
+        )
+
+    def capture_pane(self, lines: int = 80) -> str:
+        return self.repl.capture_pane(lines)
+
+    def clear_composer(self) -> None:
+        self.repl.clear_composer()
+
+    def session_file(self) -> Path:
+        return self.repl.session_file()
+
+    def _event_from_json_line(self, line: str) -> AgentEvent | None:
+        try:
+            record = json.loads(line)
+        except json.JSONDecodeError:
+            return None
+        if not isinstance(record, dict):
+            return None
+
+        kind = record.get("type")
+        payload = record.get("payload") if isinstance(record.get("payload"), dict) else {}
+        if kind == "event_msg":
+            payload_type = payload.get("type")
+            if payload_type == "user_message":
+                return AgentEvent("user", str(payload.get("message") or ""), source_head=self.name)
+            if payload_type == "agent_message" and payload.get("phase") == "final_answer":
+                return AgentEvent("assistant", str(payload.get("message") or ""), source_head=self.name)
+
+        if kind == "response_item":
+            if payload.get("type") == "message" and payload.get("role") == "assistant":
+                phase = payload.get("phase") or payload.get("metadata", {}).get("phase")
+                if phase != "final_answer":
+                    return None
+                content = payload.get("content")
+                if isinstance(content, list):
+                    parts = [
+                        str(item.get("text") or "")
+                        for item in content
+                        if isinstance(item, dict) and item.get("type") == "output_text"
+                    ]
+                    return AgentEvent("assistant", "\n".join(parts), source_head=self.name)
+        return None

agent_runtime/approvals.py

@@ -0,0 +1,87 @@
+"""Approval request model with expiry and cancellation state."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, replace
+
+
+@dataclass(frozen=True)
+class ApprovalOption:
+    number: str
+    label: str
+    key: str
+
+    @property
+    def short_label(self) -> str:
+        label = self.label.strip()
+        lowered = label.lower()
+        if "don't ask" in lowered or "do not ask" in lowered:
+            return "Yes, don't ask again"
+        if lowered.startswith("no"):
+            return "No"
+        if lowered.startswith("yes"):
+            return "Yes"
+        return label[:40] or self.number
+
+
+@dataclass(frozen=True)
+class ApprovalRequest:
+    approval_id: str
+    source_head: str
+    command: str
+    reason: str
+    options: tuple[ApprovalOption, ...]
+    expires_at: float
+    cancelled: bool = False
+
+    @classmethod
+    def create(
+        cls,
+        approval_id: str,
+        source_head: str,
+        command: str,
+        reason: str,
+        options: tuple[ApprovalOption, ...],
+        ttl_seconds: int,
+        now: float | None = None,
+    ) -> "ApprovalRequest":
+        base = time.time() if now is None else now
+        return cls(
+            approval_id=approval_id,
+            source_head=source_head,
+            command=command,
+            reason=reason,
+            options=options,
+            expires_at=base + max(1, ttl_seconds),
+        )
+
+    @property
+    def signature(self) -> str:
+        return self.approval_id
+
+    @property
+    def short_signature(self) -> str:
+        return self.approval_id[:16]
+
+    def is_expired(self, now: float | None = None) -> bool:
+        current = time.time() if now is None else now
+        return current >= self.expires_at
+
+    def is_active(self, now: float | None = None) -> bool:
+        return not self.cancelled and not self.is_expired(now)
+
+    def cancel(self) -> "ApprovalRequest":
+        return replace(self, cancelled=True)
+
+    def option(self, choice: str) -> ApprovalOption | None:
+        return next((item for item in self.options if item.number == choice), None)
+
+    def telegram_text(self) -> str:
+        lines = [f"{self.source_head} is waiting for command approval.", ""]
+        if self.command:
+            lines.extend(["Command:", self.command[:600], ""])
+        if self.reason:
+            lines.extend(["Reason:", self.reason[:600], ""])
+        lines.append("Choose a button, or reply with the visible number/shortcut.")
+        return "\n".join(lines)

agent_runtime/capabilities.py

@@ -0,0 +1,59 @@
+"""Capability declarations for Codex runtime heads."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class HeadCapabilities:
+    head: str
+    vision: bool = False
+    audio: bool = False
+    video: bool = False
+    repl: bool = False
+    approval: bool = False
+    streaming: bool = False
+    workdir_access: tuple[Path, ...] = ()
+    notes: tuple[str, ...] = ()
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "head": self.head,
+            "vision": self.vision,
+            "audio": self.audio,
+            "video": self.video,
+            "repl": self.repl,
+            "approval": self.approval,
+            "streaming": self.streaming,
+            "workdir_access": [str(path) for path in self.workdir_access],
+            "notes": list(self.notes),
+        }
+
+
+@dataclass
+class CapabilityRegistry:
+    _heads: dict[str, HeadCapabilities] = field(default_factory=dict)
+
+    def register(self, capabilities: HeadCapabilities) -> None:
+        if not capabilities.head:
+            raise ValueError("head capability name is required")
+        self._heads[capabilities.head] = capabilities
+
+    def get(self, head: str) -> HeadCapabilities | None:
+        return self._heads.get(head)
+
+    def require(self, head: str) -> HeadCapabilities:
+        capabilities = self.get(head)
+        if capabilities is None:
+            raise KeyError(f"unknown head: {head}")
+        return capabilities
+
+    def supports(self, head: str, capability: str) -> bool:
+        capabilities = self.require(head)
+        value = getattr(capabilities, capability, None)
+        return bool(value)
+
+    def as_dict(self) -> dict[str, dict[str, object]]:
+        return {head: caps.as_dict() for head, caps in sorted(self._heads.items())}

agent_runtime/locks.py

@@ -0,0 +1,111 @@
+"""Workdir lock primitive for multi-head control planes."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import hashlib
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class WorkdirLockError(RuntimeError):
+    pass
+
+
+def _process_alive(pid: int) -> bool:
+    if pid <= 0:
+        return False
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+def _lock_name(workdir: Path) -> str:
+    resolved = str(workdir.expanduser().resolve())
+    digest = hashlib.sha1(resolved.encode("utf-8", errors="replace")).hexdigest()[:16]
+    basename = workdir.name or "workdir"
+    safe_base = "".join(ch if ch.isalnum() or ch in {"-", "_", "."} else "-" for ch in basename)
+    return f"{safe_base[:80]}-{digest}"
+
+
+@dataclass
+class WorkdirLock:
+    workdir: Path
+    state_dir: Path
+    owner: str
+    stale_seconds: int = 24 * 60 * 60
+
+    def __post_init__(self) -> None:
+        self.workdir = self.workdir.expanduser().resolve()
+        self.state_dir = self.state_dir.expanduser().resolve()
+        self.lock_file = self.state_dir / "workdir-locks" / f"{_lock_name(self.workdir)}.lock"
+        self.acquired = False
+
+    def _payload(self) -> dict[str, object]:
+        return {
+            "owner": self.owner,
+            "pid": os.getpid(),
+            "workdir": str(self.workdir),
+            "created_at": time.time(),
+        }
+
+    def _existing_payload(self) -> dict[str, object]:
+        try:
+            return json.loads(self.lock_file.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return {}
+
+    def _remove_stale_lock_if_possible(self) -> bool:
+        payload = self._existing_payload()
+        pid = int(payload.get("pid") or 0)
+        created_at = float(payload.get("created_at") or 0)
+        if pid and _process_alive(pid):
+            return False
+        if created_at and time.time() - created_at < self.stale_seconds:
+            return False
+        try:
+            self.lock_file.unlink()
+            return True
+        except OSError:
+            return False
+
+    def acquire(self) -> None:
+        self.lock_file.parent.mkdir(parents=True, exist_ok=True)
+        while True:
+            try:
+                fd = os.open(str(self.lock_file), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+            except FileExistsError as exc:
+                if self._remove_stale_lock_if_possible():
+                    continue
+                payload = self._existing_payload()
+                raise WorkdirLockError(
+                    f"workdir already locked by {payload.get('owner', 'unknown')}: {self.workdir}"
+                ) from exc
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                json.dump(self._payload(), handle)
+            self.acquired = True
+            return
+
+    def release(self) -> None:
+        if not self.acquired:
+            return
+        payload = self._existing_payload()
+        if int(payload.get("pid") or 0) == os.getpid() and payload.get("owner") == self.owner:
+            try:
+                self.lock_file.unlink()
+            except OSError:
+                pass
+        self.acquired = False
+
+    def __enter__(self) -> "WorkdirLock":
+        self.acquire()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.release()

agent_runtime/transport.py

@@ -0,0 +1,77 @@
+"""Transport abstractions for local control-plane input."""
+
+from __future__ import annotations
+
+import os
+import queue
+import select
+import time
+from pathlib import Path
+from typing import Protocol
+
+
+class Transport(Protocol):
+    def send(self, message: str) -> None:
+        raise NotImplementedError
+
+    def recv(self, timeout: float | None = None) -> str:
+        raise NotImplementedError
+
+    def close(self) -> None:
+        raise NotImplementedError
+
+
+class QueueTransport:
+    def __init__(self) -> None:
+        self._queue: queue.Queue[str] = queue.Queue()
+
+    def send(self, message: str) -> None:
+        self._queue.put(message)
+
+    def recv(self, timeout: float | None = None) -> str:
+        return self._queue.get(timeout=timeout)
+
+    def close(self) -> None:
+        return None
+
+
+class FifoTransport:
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        if not self.path.exists():
+            os.mkfifo(self.path, 0o600)
+
+    def send(self, message: str) -> None:
+        with self.path.open("w", encoding="utf-8") as fifo:
+            fifo.write(message.rstrip("\n") + "\n")
+
+    def recv(self, timeout: float | None = None) -> str:
+        if timeout is None:
+            with self.path.open("r", encoding="utf-8") as fifo:
+                return fifo.readline().rstrip("\n")
+
+        deadline = time.monotonic() + max(0.0, timeout)
+        fd = os.open(self.path, os.O_RDONLY | os.O_NONBLOCK)
+        try:
+            chunks: list[bytes] = []
+            while True:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise TimeoutError(f"timed out waiting for FIFO input: {self.path}")
+                readable, _, _ = select.select([fd], [], [], remaining)
+                if not readable:
+                    raise TimeoutError(f"timed out waiting for FIFO input: {self.path}")
+                data = os.read(fd, 4096)
+                if not data:
+                    time.sleep(min(0.05, max(0.0, deadline - time.monotonic())))
+                    continue
+                chunks.append(data)
+                if b"\n" in data:
+                    break
+            return b"".join(chunks).split(b"\n", 1)[0].decode("utf-8", errors="replace")
+        finally:
+            os.close(fd)
+
+    def close(self) -> None:
+        return None

agent_runtime/types.py

@@ -0,0 +1,33 @@
+"""Common message and event types shared by head adapters."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+
+AgentEventKind = Literal[
+    "started",
+    "user",
+    "assistant",
+    "approval_requested",
+    "approval_resolved",
+    "error",
+    "stopped",
+]
+
+
+@dataclass(frozen=True)
+class AgentMessage:
+    text: str
+    media_paths: tuple[Path, ...] = ()
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class AgentEvent:
+    kind: AgentEventKind
+    text: str = ""
+    source_head: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)