The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
"""Durable per-channel receive cursors for the Buzz adapter (#90464): a restart resumes from the saved
cursor instead of reseeding from history and marking downtime arrivals as seen."""
import asyncio
import json
import logging
from pathlib import Path
logger = logging.getLogger(__name__)
_SEEN_CAP = 500 # per-channel de-dupe set bound (events)
_CURSOR_STATE_SUBDIR = "buzz" # per-channel cursors survive a restart under HERMES_HOME
_CURSOR_STATE_FILENAME = "channel-cursors.json"
class BuzzCursorMixin:
@staticmethod
def _cursor_path() -> Path:
from hermes_constants import get_hermes_home
return get_hermes_home() / _CURSOR_STATE_SUBDIR / _CURSOR_STATE_FILENAME
def _load_cursors(self) -> None:
"""Read persisted cursors; another identity/relay's file is ignored (ids collide), failures seed from history."""
self._restored_cursors = {}
try:
if not (path := self._cursor_path()).exists():
return
data = json.loads(path.read_text(encoding="utf-8-sig"))
except Exception:
logger.debug("Buzz: could not read channel cursors", exc_info=True)
return
if not isinstance(data, dict) or data.get("identity") != self._self_pubkey or data.get("relay") != self.relay_url:
return
if not isinstance(channels := data.get("channels"), dict):
return
for channel_id, entry in channels.items():
if not isinstance(entry, dict):
continue
try:
last_ts = int(entry.get("last_ts") or 0)
except (TypeError, ValueError):
continue
raw_seen = entry.get("seen")
seen = [str(event_id) for event_id in raw_seen][-_SEEN_CAP:] if isinstance(raw_seen, list) else []
self._restored_cursors[str(channel_id)] = {"chat_type": str(entry.get("chat_type") or ""), "last_ts": last_ts, "seen": seen}
def _cursor_payload(self) -> dict:
"""Snapshot of every watched channel's cursor (taken on the loop: ``_channel_state`` is loop-owned)."""
channels = {
channel_id: {
"chat_type": state.get("chat_type") or "group", "last_ts": int(state.get("last_ts") or 0),
"seen": list(state.get("seen") or ()),
}
for channel_id, state in self._channel_state.items()
}
return {"identity": self._self_pubkey, "relay": self.relay_url, "channels": channels}
def _save_cursors(self) -> None:
"""Persist every watched channel's cursor. Never raises."""
self._write_cursors(self._cursor_path(), self._cursor_payload())
@staticmethod
def _write_cursors(path: Path, payload: dict) -> None:
try:
from utils import atomic_json_write
atomic_json_write(path, payload, indent=None)
except Exception:
logger.debug("Buzz: could not persist channel cursors", exc_info=True)
@staticmethod
def _cursor_mark(state: dict) -> tuple:
"""Cheap change detector for one channel's cursor."""
seen = state.get("seen") or ()
return int(state.get("last_ts") or 0), len(seen), (next(reversed(seen), None) if seen else None)
def _cursor_writer(self):
"""A write of the cursor as it stands now. A deferred write runs after the reader marked later
events seen before their dispatch committed, so it must never re-read the live state; and a
write older than one already landed is skipped, so the file never moves back."""
payload = self._cursor_payload()
self._cursor_snapshots = generation = self._cursor_snapshots + 1
async def persist() -> None:
# The write fsyncs + renames, and on the WebSocket transport this runs once per inbound event.
async with self._cursor_write_lock:
if generation > self._cursor_written:
self._cursor_written = generation
await asyncio.to_thread(self._write_cursors, self._cursor_path(), payload)
return persist