refactor: no comments left - one-line module docstrings, contracts on public fields only; jobs/job.py; example config and README

src/beaver_gateway/frontends/telegram/frontend.py

@@ -1,13 +1,8 @@
-"""``TelegramFrontend`` - the private chat with the bot as the window (§3.8).
+"""``TelegramFrontend`` - the private chat with the bot as the window.
 
-A private chat with topics has no General: the gateway makes one topic for
-the master (``master_topic``) and rebinds it to every new master; any other
-topic is a branch. The user makes a topic and the
-first message in it spawns the branch (``seed=morning``); a message into a
-topic whose branch is merged or closed spawns a new branch on the same
-topic. Replies stream as drafts and land through the outbox; turns that
-came from other windows are mirrored with a marker; ``origin=system`` is
-never shown. ``AskUserQuestion`` becomes inline buttons (§3.7).
+A private chat with topics has no General, so the gateway makes and rebinds
+one topic for the master; any other topic is a branch, and a message into a
+new one spawns it. Replies stream as drafts and land through the outbox.
 """
 
 from __future__ import annotations
@@ -62,13 +57,10 @@ _COMMANDS = ("merge", "new", "chat", "status", "help", "start")
 
 @dataclass(frozen=True, slots=True)
 class Attachments:
-    """Where files from Telegram go.
+    """Where files land.
 
-    Files land in ``<root>/YYYY-MM-DD/<unixts>-<name>`` (the day in ``tz``)
-    and whatever is older than ``keep_days`` is swept; ``None`` never
-    sweeps. ``ephemeral`` - under the gateway's data dir; ``vault`` -
-    ``dir`` is an inbox inside the agent's zone: the agent moves keepers
-    next to the note, the rest is swept after ``keep_days``.
+    ``ephemeral`` uses the gateway's data dir, ``vault`` an inbox under
+    ``dir``; ``keep_days`` sweeps older files, ``None`` never sweeps.
     """
 
     mode: Literal["ephemeral", "vault"] = "ephemeral"
@@ -148,8 +140,6 @@ class TelegramFrontend(Frontend):
         self._reactions: dict[int, tuple[int, int]] = {}
         self._tasks: set[asyncio.Task[None]] = set()
 
-    # ---- Frontend --------------------------------------------------------
-
     def agent_for(self, kind: Kind) -> str | None:
         return {"master": self.master_agent, "branch": self.branch_agent}.get(kind)
 
@@ -223,8 +213,6 @@ class TelegramFrontend(Frontend):
         self._topic_names[target[1]] = f"{prefix}{name}"
         return True
 
-    # ---- plumbing --------------------------------------------------------
-
     @property
     def bot(self) -> Bot:
         if self._bot is None:
@@ -355,8 +343,6 @@ class TelegramFrontend(Frontend):
             binding=(FRONTEND, self._ext(thread_id)),
         )
 
-    # ---- inbox -----------------------------------------------------------
-
     async def _handle(self, update: Update) -> None:
         if update.message is not None:
             await self._on_message(update.message)
@@ -556,8 +542,6 @@ class TelegramFrontend(Frontend):
                 if folder.is_dir() and not any(folder.iterdir()):
                     folder.rmdir()
 
-    # ---- commands --------------------------------------------------------
-
     async def _command(
         self, command: str, args: str, message: Message, thread_id: int | None
     ) -> None:
@@ -663,8 +647,6 @@ class TelegramFrontend(Frontend):
         self._tasks.add(task)
         task.add_done_callback(self._tasks.discard)
 
-    # ---- bus -------------------------------------------------------------
-
     async def _events(self) -> None:
         async for event in self.bus.stream():
             try:
@@ -790,8 +772,6 @@ class TelegramFrontend(Frontend):
                 )
         await self._deliver(conv, text, turn_id=turn_id, key=f"{turn_id}:reply")
 
-    # ---- drafts ------------------------------------------------------------
-
     async def _open_draft(
         self, key: str, event: Event, target: tuple[int, int | None]
     ) -> None:
@@ -841,8 +821,6 @@ class TelegramFrontend(Frontend):
         if draft is not None:
             await draft.stop()
 
-    # ---- questions (§3.7) ---------------------------------------------------
-
     async def _ask(
         self, conv: Conversation, event: Event, target: tuple[int, int | None]
     ) -> None: