feat(hands): vibegram read takes since and last for a non-consuming look at history

beaver_agent/hands/vibegram.py

@@ -11,9 +11,10 @@
 приходит. Поэтому клиент помнит последние события сам: тулза `read`
 показывает их, если новых нет, - мастер увидит то, что уже разобрал триаж.
 
-Там, где нужен не «что нового», а «последние N строк комнаты» (сторож),
-курсор не годится в принципе: `window` читает хвост истории через
-`/api/state`, не трогая курсор и ничего не вычёркивая.
+Там, где нужен не «что нового», а «последние N строк комнаты» (сторож) или
+«всё после события #N» (`read since=` / `read last=` у мастера), курсор не
+годится в принципе: `history` читает историю через `/api/state`, не трогая
+курсор и ничего не вычёркивая.
 """
 
 from __future__ import annotations
@@ -54,6 +55,9 @@ class Event:
     def line(self) -> str:
         return f"[{self.at}] {self.text}"
 
+    def tagged(self) -> str:
+        return f"#{self.id} {self.line()}"
+
 
 @dataclass(frozen=True, slots=True)
 class Window:
@@ -87,12 +91,19 @@ class Vibegram:
         note: str | None = None,
         about: str | None = None,
         skills: list[str] | None = None,
+        since: int | None = None,
+        last: int | None = None,
     ) -> str:
         """Вайбграм - комната агентов (чужие клоды и ты) вокруг общей репы.
 
         action:
         - read: что нового с прошлого раза (сообщения, claim'ы, план); если
-          нового нет - последние уже виденные события.
+          нового нет - последние уже виденные события. Курсор общий с
+          крон-триажем: прочитанное здесь второй раз не придёт.
+        - read since=N / read last=N: история комнаты - всё после события #N
+          или последние N сообщений. Ничего не съедает, спрашивать можно
+          сколько угодно раз. Вывод «сосед молчит» брать только отсюда: пустой
+          read - это «крон уже выгреб», а не «никто не ответил».
         - send: написать в комнату (text). Это доска объявлений, не чат:
           пиши, когда добавляешь информацию; адресовать - @ник.
         - who: кто в комнате, что умеет, что держит.
@@ -107,7 +118,7 @@ class Vibegram:
         """
         match action:
             case "read":
-                return await self._read()
+                return await self._read(since=since, last=last)
             case "send":
                 return await self._send(_need(text, "text"))
             case "who":
@@ -189,9 +200,19 @@ class Vibegram:
         `viewToken` спрашиваем каждый раз заново: протухший в кэше ключ - ровно
         то тихое враньё, ради которого окно и переписано.
         """
+        return await self.history(limit=limit, pages=pages)
+
+    async def history(
+        self, *, after: int = 0, limit: int | None = None, pages: int = PAGES
+    ) -> Window:
+        """Сообщения комнаты после события `after`, хвостом не длиннее `limit`.
+
+        Непотребляющий проход по `/api/state`: курсор `/api/pending` остаётся
+        там, где стоял, поэтому спрашивать можно сколько угодно раз.
+        `limit=None` - всё, что нашлось после `after`.
+        """
         view = quote(str((await self._get("/api/room"))["room"]["viewToken"]))
         tail: deque[Event] = deque(maxlen=limit)
-        after = 0
         full = False
         for _ in range(pages):
             page = await self._get(f"/api/state?view={view}&after={after}")
@@ -222,15 +243,36 @@ class Vibegram:
         needle = f"@{self.nick}".lower()
         return any(needle in e.text.lower() for e in events)
 
-    async def _read(self) -> str:
+    async def _read(self, *, since: int | None = None, last: int | None = None) -> str:
+        if since is not None or last is not None:
+            return await self._history(since=since, last=last)
         fresh = await self.pending()
         if fresh:
-            return self._clip("\n".join(e.line() for e in fresh))
+            return self._clip("\n".join(e.tagged() for e in fresh))
         if self._recent:
-            tail = "\n".join(e.line() for e in list(self._recent)[-10:])
+            tail = "\n".join(e.tagged() for e in list(self._recent)[-10:])
             return f"нового нет; последнее, что было:\n{tail}"
         return "нового нет"
 
+    async def _history(self, *, since: int | None, last: int | None) -> str:
+        if last is not None and last <= 0:
+            msg = "last - сколько последних сообщений показать, нужно число больше нуля"
+            raise ValueError(msg)
+        after = max(since or 0, 0)
+        window = await self.history(after=after, limit=last)
+        if not window.events:
+            if not window.full:
+                return f"историю после #{after} не дочитали до конца, пусто пока"
+            return (
+                f"после #{after} сообщений нет (история дочитана)"
+                if after
+                else "сообщений в комнате нет"
+            )
+        lines = [e.tagged() for e in window.events]
+        if not window.full:
+            lines.insert(0, "окно неполное: до конца истории не дочитали")
+        return self._clip("\n".join(lines))
+
     async def _send(self, text: str) -> str:
         try:
             await self._post("/api/messages", {"body": text})