All plugins

gateway-guardian

Telegram/gateway reliability guard for Hermes — detects 409 polling conflicts, duplicate pollers, freezes, stale locks and missed deliveries, shows one health state (OK/DEGRADED/BLOCKED) and an approved recovery plan. Disclosure — read-only status: it reads the last 256 KiB of the gateway.log of this Hermes home and of every profile under it, plus process command lines from /proc, and returns only pattern counts and file paths; recovery only prints a fixed checklist and appends the chosen action to a local intent log, and never restarts, kills or rebinds anything itself; no network calls, no credentials, no telemetry.

kawsthingzToolsv1.0.0Updated 1 hour ago

About

Telegram/gateway reliability guard for Hermes — detects 409 polling conflicts, duplicate pollers, freezes, stale locks and missed deliveries, shows one health state (OK/DEGRADED/BLOCKED) and an approved recovery plan. Disclosure — read-only status: it reads the last 256 KiB of the gateway.log of this Hermes home and of every profile under it, plus process command lines from /proc, and returns only pattern counts and file paths; recovery only prints a fixed checklist and appends the chosen action to a local intent log, and never restarts, kills or rebinds anything itself; no network calls, no credentials, no telemetry.

Hermes Gateway Guardian

A small, read-only reliability guard for Hermes gateway and Telegram operation.

The 2 a.m. silent Telegram

You wake up and your Hermes Telegram bot has been quiet for hours. Customers sent messages. Your agent says the gateway is running. Nothing reached the user.

The cause is usually boring and invisible: two pollers for one token, a 409 conflict storm, a frozen gateway, or a stale lock after a restart. The worst part is the silence. A loud error is annoying. A silent failure erodes trust.

Gateway Guardian exists for that moment. It watches the gateway and tells you, in one line, whether Telegram can actually reach the user: OK, DEGRADED, or BLOCKED, with the exact cause.

Why

Hermes users hit the same painful class of failure: Telegram goes quiet, a 409 polling conflict appears (two pollers, one token), the gateway freezes, or a stale lock blocks restart. The agent often reports "gateway running" while no reply can reach the user. Gateway Guardian makes that state visible in one place.

What it does

  • gateway_guardian_status — scans recent gateway logs and process list for:
    • 409 / polling conflicts
    • duplicate pollers
    • freeze / unresponsive signals
    • stale locks
    • missed / failed deliveries
    • returns one state: OK, DEGRADED, or BLOCKED, with the exact cause and pattern counts.
  • gateway_guardian_recover — records the recovery intent and returns the exact operator plan. It never restarts, kills or rebinds anything by itself.
  • /gateway-guardian — slash command that prints the status.

Safety

  • Read-only status by default.
  • Recovery is approval-gated: the tool prints commands, the operator approves and runs them.
  • No message bodies are stored. Only pattern counts and recovery intents are kept.

Demo

  1. Healthy gateway: status is OK.
  2. Start a duplicate poller or freeze a lane: status becomes BLOCKED with the exact cause.
  3. Run the approved recovery plan from gateway_guardian_recover.
  4. Status returns to OK and the intent log shows the action.

Validate

hermes plugins validate /root/.hermes/plugins/gateway-guardian --install-deps
hermes plugins doctor gateway-guardian --ci

README from the reviewed commit f9959e4; it updates when the author re-pins.