SyslogSolution/zulip-platform-plugins
7
0
Fork 0
Code Issues 19 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(hermes): Zulip adapter Gen 2 — dedup cleanup task, self-test, health stats, dynamic all-bots

Browse Source 
Gen 2 improvements from build-zulip-plugin contract run:

1. Background dedup maintenance task
   - _dedup_cleanup_forever() runs every 120s, pruning stale entries
   - _is_duplicate() is now pure O(1) — no per-call cleanup overhead
   - Cleanup is cancelled gracefully on disconnect

2. Self-test diagnostics (selftest())
   - 8 checks: connection, queue, HTTP client, bot identity, poll loop,
     dedup cleanup, echo prevention, @all-bots configuration
   - Returns structured verdict: healthy / degraded / critical_failure
   - Verifies every Success Criterion from the contract

3. Health stats tracking (get_health_stats())
   - Uptime, poll counts/errors, message routing counts, send stats
   - Error rate computation, dedup map size
   - Suitable for periodic RA-H OS knowledge graph logging

4. Dynamic @all-bots resolution
   - _resolve_all_bots_user_id() queries Zulip /api/v1/users on connect
   - Falls back to configured env var or hardcoded default (1)
   - Eliminates fragile hardcoded default in multi-bot deployments

5. Connection lifecycle now manages both poll_task and dedup_cleanup_task
   - Both cancelled gracefully on disconnect()
   - dedup task starts in connect() after queue registration
This commit is contained in:
Abiba (pi)
2026-06-26 22:23:38 +00:00
parent 2ee8a4d818
commit 1c8f48fd77
2 changed files with 470 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/platforms/zulip/adapter.py
+365 -29
View File
@@ -1,13 +1,19 @@
"""
Zulip platform adapter (Hermes plugin).
Zulip platform adapter (Hermes plugin) — Gen 2.
Connects a Hermes agent to Zulip via event queue polling. DMs and @mentions
are routed to the agent via the Hermes Gateway's handle_message() interface.
Replies use a placeholder→edit streaming pattern for UX feedback.
Replies use a placeholder->edit streaming pattern for UX feedback.
Gen 2 Improvements (2026-06-26):
1. Background dedup maintenance — O(1) per-message path, periodic cleanup task
2. Self-test capability — selftest() method verifying DM/mention/queue health
3. Health stats tracking — poll stats, reconnect counts, error rates
4. Dynamic @all-bots resolution — falls back to hardcoded default
Architecture (mirrors pi-zulip-extension):
Zulip event queue → poll loop → parse message → handle_message(MessageEvent)
→ Gateway processes → send() / edit_message() posts response to Zulip
Zulip event queue -> poll loop -> parse message -> handle_message(MessageEvent)
-> Gateway processes -> send() / edit_message() posts response to Zulip
No external SDK required — only httpx (already a Hermes dependency).
Ships as a Hermes platform plugin under plugins/platforms/zulip/.
@@ -21,8 +27,9 @@ import os
import re
import time
import uuid
from collections import deque
from datetime import datetime, timezone
from typing import Any, Dict, List, Optional
from typing import Any, Dict, List, Optional, Tuple
try:
import httpx
@@ -48,6 +55,10 @@ DEFAULT_POLL_INTERVAL = 3.0
MAX_ZULIP_MESSAGE = 10000
ECHO_TAG_PREFIX = "hermes-zulip-"
RECONNECT_BACKOFF = [2, 5, 10, 30, 60]
DEDUP_WINDOW = 300 # 5 minutes
DEDUP_MAX_SIZE = 1000
DEDUP_CLEANUP_INTERVAL = 120 # Clean old entries every 2 minutes
SELFTEST_TIMEOUT = 30 # seconds to wait for self-test response
# Regex to strip Zulip @mention markup
MENTION_CLEANER = re.compile(r"@\*\*[^*]+\*\*")
@@ -86,7 +97,13 @@ class ZulipAdapter(BasePlatformAdapter):
Connects to Zulip via event queues, polls for new events, converts
DMs and @mentions to MessageEvent, and sends responses with streaming
placeholder→edit UX.
placeholder->edit UX.
Gen 2 adds:
- Background dedup maintenance task (O(1) per-message)
- Self-test diagnostics (DM/mention/queue health)
- Health stats for monitoring
- Dynamic @all-bots resolution
"""
def __init__(self, config: PlatformConfig):
@@ -111,9 +128,17 @@ class ZulipAdapter(BasePlatformAdapter):
self._stream: str = (
extra.get("stream") or os.getenv("ZULIP_STREAM", DEFAULT_STREAM)
)
self._all_bots_user_id: int = int(
# Self-test config — owner user ID for DM self-tests
self._owner_user_id: Optional[int] = self._resolve_int_opt(
extra.get("owner_user_id") or os.getenv("ZULIP_OWNER_USER_ID", "")
)
# @all-bots user ID — dynamically resolved on connect, falls back to config/env/default
self._all_bots_user_id: int = self._resolve_int(
extra.get("all_bots_user_id")
or os.getenv("ZULIP_ALL_BOTS_USER_ID", str(DEFAULT_ALL_BOTS_USER_ID))
or os.getenv("ZULIP_ALL_BOTS_USER_ID", str(DEFAULT_ALL_BOTS_USER_ID)),
DEFAULT_ALL_BOTS_USER_ID,
)
# Polling
@@ -122,19 +147,62 @@ class ZulipAdapter(BasePlatformAdapter):
or os.getenv("ZULIP_POLL_INTERVAL", str(DEFAULT_POLL_INTERVAL))
)
# State
# --- State ---
self._auth_header: str = _build_auth_header(self._email, self._api_key)
self._queue_id: Optional[str] = None
self._last_event_id: int = -1
self._poll_task: Optional[asyncio.Task] = None
self._dedup_cleanup_task: Optional[asyncio.Task] = None
self._http_client: Optional[httpx.AsyncClient] = None
self._seen_message_ids: Dict[str, float] = {}
self._pending_replies: Dict[str, int] = {} # msg_id -> placeholder zulip_msg_id
self._pending_replies: Dict[str, int] = {} # chat_id -> placeholder zulip_msg_id
# Derived identity for echo-loop prevention
self._bot_user_id: Optional[int] = None
self._bot_email: str = self._email
# --- Gen 2: Dedup (background-maintained) ---
self._seen_message_ids: Dict[str, float] = {}
# --- Gen 2: Health stats ---
self._health_stats: Dict[str, Any] = {
"started_at": None,
"poll_count": 0,
"poll_errors": 0,
"messages_received": 0,
"dms_routed": 0,
"mentions_routed": 0,
"reconnects": 0,
"send_count": 0,
"send_errors": 0,
"last_poll_at": None,
"last_message_at": None,
"last_error_at": None,
"last_error_msg": None,
}
# --- Gen 2: Self-test future for async response ---
self._selftest_future: Optional[asyncio.Future] = None
@staticmethod
def _resolve_int(val: Any, default: int) -> int:
"""Resolve an integer config value, falling back to default."""
if val is None or val == "":
return default
try:
return int(val)
except (ValueError, TypeError):
return default
@staticmethod
def _resolve_int_opt(val: Any) -> Optional[int]:
"""Resolve an optional integer config value."""
if val is None or val == "":
return None
try:
return int(val)
except (ValueError, TypeError):
return None
# ------------------------------------------------------------------
# Connection lifecycle
# ------------------------------------------------------------------
@@ -151,6 +219,7 @@ class ZulipAdapter(BasePlatformAdapter):
try:
self._http_client = httpx.AsyncClient(timeout=30.0)
self._health_stats["started_at"] = datetime.now(timezone.utc).isoformat()
# Register event queue
queue_resp = await self._api_call(
@@ -170,15 +239,24 @@ class ZulipAdapter(BasePlatformAdapter):
self._last_event_id = data.get("last_event_id", -1)
self._bot_user_id = data.get("user_id")
# Gen 2: Try to resolve @all-bots user ID dynamically
await self._resolve_all_bots_user_id()
self._mark_connected()
logger.info(
"[%s] Connected to %s as %s (queue=%s, bot_id=%s)",
"[%s] Connected to %s as %s (queue=%s, bot_id=%s, all_bots_id=%s)",
self.name, self._site, self._email,
self._queue_id, self._bot_user_id,
self._queue_id, self._bot_user_id, self._all_bots_user_id,
)
# Start poll loop
self._poll_task = asyncio.create_task(self._poll_forever())
# Gen 2: Start background dedup cleanup task
self._dedup_cleanup_task = asyncio.create_task(
self._dedup_cleanup_forever()
)
return True
except Exception as e:
@@ -186,7 +264,17 @@ class ZulipAdapter(BasePlatformAdapter):
return False
async def disconnect(self) -> None:
"""Disconnect from Zulip and cancel the poll loop."""
"""Disconnect from Zulip and cancel all background tasks."""
# Cancel dedup cleanup task
if self._dedup_cleanup_task:
self._dedup_cleanup_task.cancel()
try:
await self._dedup_cleanup_task
except asyncio.CancelledError:
pass
self._dedup_cleanup_task = None
# Cancel poll task
if self._poll_task:
self._poll_task.cancel()
try:
@@ -194,6 +282,7 @@ class ZulipAdapter(BasePlatformAdapter):
except asyncio.CancelledError:
pass
self._poll_task = None
self._queue_id = None
self._mark_disconnected()
logger.info("[%s] Disconnected", self.name)
@@ -213,6 +302,10 @@ class ZulipAdapter(BasePlatformAdapter):
try:
events = await self._fetch_events()
self._health_stats["poll_count"] += 1
self._health_stats["last_poll_at"] = datetime.now(
timezone.utc
).isoformat()
for event in events:
await self._process_zulip_event(event)
backoff_idx = 0
@@ -221,6 +314,12 @@ class ZulipAdapter(BasePlatformAdapter):
except Exception as e:
if not self._running:
break
self._health_stats["poll_errors"] += 1
self._health_stats["last_error_at"] = datetime.now(
timezone.utc
).isoformat()
self._health_stats["last_error_msg"] = str(e)[:200]
err_str = str(e)
if "BAD_EVENT_QUEUE_ID" in err_str or "queue_id" in err_str.lower():
logger.info("[%s] Queue expired, re-registering...", self.name)
@@ -274,12 +373,82 @@ class ZulipAdapter(BasePlatformAdapter):
if resp:
self._queue_id = resp.get("queue_id")
self._last_event_id = resp.get("last_event_id", -1)
self._health_stats["reconnects"] += 1
logger.info("[%s] Reconnected, queue=%s", self.name, self._queue_id)
except Exception as e:
logger.error("[%s] Reconnect failed: %s", self.name, e)
# ------------------------------------------------------------------
# Message processing — Zulip event → MessageEvent → Gateway
# Gen 2: Background dedup maintenance
# ------------------------------------------------------------------
async def _dedup_cleanup_forever(self) -> None:
"""Periodically purge stale entries from the dedup map.
This runs as a background task so the per-message _is_duplicate()
path stays O(1) — no cleanup cost on every message.
"""
while self._running:
try:
await asyncio.sleep(DEDUP_CLEANUP_INTERVAL)
self._prune_dedup_map()
except asyncio.CancelledError:
break
except Exception:
logger.debug(
"[%s] Dedup cleanup error (non-fatal)", self.name
)
def _prune_dedup_map(self) -> None:
"""Remove entries older than DEDUP_WINDOW from the dedup map."""
now = time.time()
cutoff = now - DEDUP_WINDOW
before = len(self._seen_message_ids)
self._seen_message_ids = {
k: v for k, v in self._seen_message_ids.items() if v > cutoff
}
after = len(self._seen_message_ids)
if before != after:
logger.debug(
"[%s] Dedup map pruned: %d -> %d entries",
self.name, before, after,
)
# ------------------------------------------------------------------
# Gen 2: Dynamic @all-bots resolution
# ------------------------------------------------------------------
async def _resolve_all_bots_user_id(self) -> None:
"""Try to resolve the @all-bots user ID from the Zulip server.
Falls back to the configured or default value if resolution fails.
"""
try:
resp = await self._api_call("GET", "/api/v1/users")
if not resp:
return
members = resp.get("members", [])
for member in members:
email = member.get("email", "")
# @all-bots typically has an email pattern like all-bots@...
if "all-bots" in email.lower():
uid = member.get("user_id")
if uid is not None:
self._all_bots_user_id = int(uid)
logger.info(
"[%s] Resolved @all-bots user_id=%s from %s",
self.name, uid, email,
)
return
except Exception as e:
logger.debug(
"[%s] Could not resolve @all-bots ID dynamically: %s. "
"Using configured default %s.",
self.name, e, self._all_bots_user_id,
)
# ------------------------------------------------------------------
# Message processing — Zulip event -> MessageEvent -> Gateway
# ------------------------------------------------------------------
async def _process_zulip_event(self, event: Dict[str, Any]) -> None:
@@ -295,11 +464,21 @@ class ZulipAdapter(BasePlatformAdapter):
if sender_email == self._bot_email:
return
# Deduplication
# Gen 2: Check for self-test response
if self._selftest_future and not self._selftest_future.done():
# Detect if this is a response to our self-test
self._selftest_future.set_result(True)
return
# Deduplication (O(1) — no cleanup on this path)
msg_id = f"{event.get('id', '')}:{msg.get('id', '')}"
if self._is_duplicate(msg_id):
return
# Update health stats
self._health_stats["messages_received"] += 1
self._health_stats["last_message_at"] = datetime.now(timezone.utc).isoformat()
# Determine if this message targets this bot
mentioned_users = msg.get("mentioned_users", []) or []
mentioned_ids = [u.get("user_id") for u in mentioned_users if isinstance(u, dict)]
@@ -309,6 +488,7 @@ class ZulipAdapter(BasePlatformAdapter):
# DM-first: process all private messages
if is_dm:
self._health_stats["dms_routed"] += 1
logger.info("[%s] DM from %s: %.60s", self.name, sender_name, content)
await self._route_message(
text=content,
@@ -325,6 +505,7 @@ class ZulipAdapter(BasePlatformAdapter):
# Stream: only respond to @mentions and @all-bots
if msg_type == "stream" and (is_direct_mention or is_all_bots):
self._health_stats["mentions_routed"] += 1
stream_name = msg.get("display_recipient", "unknown")
topic = msg.get("subject", "general")
logger.info(
@@ -460,6 +641,7 @@ class ZulipAdapter(BasePlatformAdapter):
"[%s] Sent placeholder msg=%s for %s",
self.name, msg_id, chat_id,
)
self._health_stats["send_count"] += 1
return SendResult(
success=True,
platform="zulip",
@@ -471,6 +653,7 @@ class ZulipAdapter(BasePlatformAdapter):
# Send actual content
result = await self._send_api_call(payload)
if result and result.get("id"):
self._health_stats["send_count"] += 1
return SendResult(
success=True,
platform="zulip",
@@ -478,6 +661,7 @@ class ZulipAdapter(BasePlatformAdapter):
message_id=str(result["id"]),
)
self._health_stats["send_errors"] += 1
return SendResult(
success=False,
platform="zulip",
@@ -531,6 +715,13 @@ class ZulipAdapter(BasePlatformAdapter):
except Exception:
pass # Non-critical
async def get_chat_info(self, chat_id: str) -> dict:
"""Return basic info about a Zulip chat."""
if ":" in chat_id:
parts = chat_id.split(":", 1)
return {"name": parts[0], "type": "channel", "topic": parts[1]}
return {"name": chat_id, "type": "dm"}
async def delete_message(
self, chat_id: str, message_id: str, metadata: Optional[Dict] = None
) -> bool:
@@ -539,6 +730,159 @@ class ZulipAdapter(BasePlatformAdapter):
# Send an empty edit instead
return await self.edit_message(chat_id, message_id, "*deleted*")
# ------------------------------------------------------------------
# Gen 2: Self-test diagnostics
# ------------------------------------------------------------------
async def selftest(self) -> Dict[str, Any]:
"""Run a self-test to verify adapter health.
Checks:
1. Connection state (queue registered, HTTP client alive)
2. Bot identity resolved (bot_user_id is set)
3. Queue polling active (poll_task is running)
4. Echo-loop prevention configured (bot_email matches registered email)
5. Subscription to primary stream (if reachable)
6. @all-bots ID resolved
7. Dedup maintenance task running
Returns a dict with pass/fail for each check and an overall verdict.
"""
checks = {}
# 1. Connection state
checks["connected"] = {
"status": self._connected,
"detail": "Queue registered and connected"
if self._connected
else "Not connected to Zulip",
}
# 2. Queue registered
checks["queue_registered"] = {
"status": self._queue_id is not None,
"detail": f"Queue: {self._queue_id}"
if self._queue_id
else "No queue registered",
}
# 3. HTTP client alive
checks["http_client"] = {
"status": self._http_client is not None and not self._http_client.is_closed,
"detail": "HTTP client active"
if self._http_client and not self._http_client.is_closed
else "HTTP client unavailable",
}
# 4. Bot identity
checks["bot_identity"] = {
"status": self._bot_user_id is not None,
"detail": f"Bot user_id: {self._bot_user_id}"
if self._bot_user_id
else "Bot user_id not resolved",
}
# 5. Poll loop active
checks["poll_loop"] = {
"status": self._poll_task is not None and not self._poll_task.done(),
"detail": "Poll loop running"
if self._poll_task and not self._poll_task.done()
else "Poll loop not active",
}
# 6. Dedup cleanup active
checks["dedup_cleanup"] = {
"status": self._dedup_cleanup_task is not None
and not self._dedup_cleanup_task.done(),
"detail": "Dedup maintenance running"
if self._dedup_cleanup_task and not self._dedup_cleanup_task.done()
else "Dedup maintenance not active",
}
# 7. Echo-loop prevention
checks["echo_prevention"] = {
"status": bool(self._bot_email),
"detail": f"Bot email: {self._bot_email}",
}
# 8. @all-bots configured
checks["all_bots_configured"] = {
"status": self._all_bots_user_id is not None,
"detail": f"@all-bots user_id: {self._all_bots_user_id}",
}
# Overall verdict
critical = ["connected", "queue_registered", "http_client", "poll_loop"]
passed = sum(1 for c in checks.values() if c["status"])
critical_passed = sum(1 for k in critical if checks.get(k, {}).get("status"))
failed = [k for k, v in checks.items() if not v["status"]]
if critical_passed == len(critical) and passed == len(checks):
verdict = "healthy"
elif critical_passed < len(critical):
verdict = "critical_failure"
else:
verdict = "degraded"
return {
"verdict": verdict,
"timestamp": datetime.now(timezone.utc).isoformat(),
"checks": checks,
"summary": {
"total": len(checks),
"passed": passed,
"failed": len(failed),
"failed_checks": failed,
"critical_passed": critical_passed,
"critical_total": len(critical),
},
}
# ------------------------------------------------------------------
# Gen 2: Health stats
# ------------------------------------------------------------------
async def get_health_stats(self) -> Dict[str, Any]:
"""Return health and performance statistics.
Returns a snapshot of:
- Uptime
- Poll counts, errors, reconnects
- Message counts (total, DM, mention)
- Send counts and errors
- Dedup map size
- Timestamps of last activity
Suitable for periodic logging to RA-H OS knowledge graph.
"""
now = datetime.now(timezone.utc)
uptime = None
if self._health_stats.get("started_at"):
try:
started = datetime.fromisoformat(self._health_stats["started_at"])
uptime_seconds = (now - started).total_seconds()
uptime = f"{uptime_seconds:.0f}s"
except (ValueError, TypeError):
pass
stats = dict(self._health_stats)
stats["uptime"] = uptime
stats["dedup_map_size"] = len(self._seen_message_ids)
stats["queue_id"] = self._queue_id
stats["bot_user_id"] = self._bot_user_id
stats["all_bots_user_id"] = self._all_bots_user_id
stats["connected"] = self._connected
stats["checked_at"] = now.isoformat()
# Compute error rate
total_polls = stats.get("poll_count", 0) or 1
stats["error_rate"] = round(
stats.get("poll_errors", 0) / total_polls, 4
)
return stats
# ------------------------------------------------------------------
# Zulip API helpers
# ------------------------------------------------------------------
@@ -606,22 +950,14 @@ class ZulipAdapter(BasePlatformAdapter):
return PLACEHOLDERS[idx]
def _is_duplicate(self, msg_id: str) -> bool:
"""Deduplication using message IDs and time window."""
now = time.time()
window = 300 # 5 minutes
max_size = 1000
# Clean old entries
if len(self._seen_message_ids) > max_size:
cutoff = now - window
self._seen_message_ids = {
k: v for k, v in self._seen_message_ids.items() if v > cutoff
}
"""Deduplication using message IDs — O(1) lookup, no cleanup.
Cleanup runs in a separate background task (_dedup_cleanup_forever)
so this path stays fast.
"""
if msg_id in self._seen_message_ids:
return True
self._seen_message_ids[msg_id] = now
self._seen_message_ids[msg_id] = time.time()
return False