fix(hermes): bound channel turns and suppress Telegram progress spam (#43)

Author: JulioMCruz

CHANGELOG.md

@@ -7,6 +7,20 @@ captures *what shipped* and the *why* — the equivalent of a good commit body,
 collected here so operators don't have to spelunk `git log`. Tag-style
 versions are optional; date-stamped sections are fine for in-flight work.
 
+## 2026-07-21
+
+### Hermes messaging loop protection
+
+Telegram now delivers only the final assistant response: token streaming,
+tool-progress bubbles, and interim assistant commentary are disabled for that
+surface, while long-running heartbeat notifications remain enabled. Hermes
+agent requests also receive a configurable `PERKOS_AGENT_MAX_TURNS` budget
+(default `30`, validated as a positive integer) instead of inheriting the
+upstream 90-turn default. This bounds malformed provider/tool combinations and
+prevents permanent Telegram progress-message spam. The guard was added after
+an invalid nested OpenClaw → Hermes-agent provider test retried missing Hermes
+tools hundreds of times from one inbound Telegram message.
+
 ## 2026-06-21
 
 ### Skill id rename: `perkos-tech` → `perkos-knowledge` (both runtimes)

images/hermes/config/hermes.template.yaml

@@ -69,6 +69,24 @@ mcp_servers:
 agent:
   id: ${PERKOS_AGENT_ID}
   name: ${PERKOS_AGENT_NAME}
+  # Bound the number of model/tool turns in one inbound request. Hermes
+  # defaults to 90, which is too permissive for messaging channels: a bad
+  # provider/tool pairing can otherwise keep a Telegram conversation active
+  # for close to an hour. Operators can raise this for long-running workers.
+  max_turns: ${PERKOS_AGENT_MAX_TURNS}
+
+# Messaging surfaces should deliver a conversational answer, not every
+# mid-turn planning sentence. Telegram has permanent bubbles, so interim
+# assistant commentary and token streaming are disabled while the final answer
+# and long-running heartbeat remain available.
+display:
+  platforms:
+    telegram:
+      tool_progress: off
+      interim_assistant_messages: false
+      busy_ack_detail: false
+      streaming: false
+      long_running_notifications: true
 
 # Standalone tool plugins staged into $HERMES_HOME/plugins/ by the entrypoint.
 # Hermes gates user/standalone plugins behind this allow-list (unset = none),

images/hermes/docker-entrypoint.sh

@@ -71,6 +71,22 @@ API_SERVER_ENABLED=$(truthy "${API_SERVER_ENABLED:-true}")
 API_SERVER_HOST="${API_SERVER_HOST:-0.0.0.0}"
 API_SERVER_PORT="${API_SERVER_PORT:-8642}"
 
+# A channel request must have a finite tool/model budget. Upstream Hermes uses
+# 90 turns by default; 30 is ample for interactive work and prevents malformed
+# provider/tool combinations from looping for an hour. Keep it configurable
+# for autonomous workers that intentionally need a larger budget.
+PERKOS_AGENT_MAX_TURNS="${PERKOS_AGENT_MAX_TURNS:-30}"
+case "$PERKOS_AGENT_MAX_TURNS" in
+  ''|*[!0-9]*)
+    echo "perkos-entrypoint: PERKOS_AGENT_MAX_TURNS must be a positive integer" >&2
+    exit 2
+    ;;
+esac
+if [ "$PERKOS_AGENT_MAX_TURNS" -lt 1 ]; then
+  echo "perkos-entrypoint: PERKOS_AGENT_MAX_TURNS must be at least 1" >&2
+  exit 2
+fi
+
 # Messaging gateways default OFF — a wallet enables them via the
 # /agents/new wizard which sets *_ENABLED via ecsProvision.
 TELEGRAM_ENABLED=$(truthy "${TELEGRAM_ENABLED:-}")
@@ -80,7 +96,7 @@ SLACK_ENABLED=$(truthy "${SLACK_ENABLED:-}")
 SLACK_CHANNEL_ID="${SLACK_CHANNEL_ID:-}"
 FARCASTER_ENABLED=$(truthy "${FARCASTER_ENABLED:-}")
 
-export API_SERVER_ENABLED API_SERVER_HOST API_SERVER_PORT
+export API_SERVER_ENABLED API_SERVER_HOST API_SERVER_PORT PERKOS_AGENT_MAX_TURNS
 export TELEGRAM_ENABLED TELEGRAM_ALLOWED_USERS TELEGRAM_HOME_CHANNEL
 export SLACK_ENABLED SLACK_CHANNEL_ID
 export FARCASTER_ENABLED

tests/hermes/smoke.sh

@@ -235,6 +235,24 @@ else
   fail "config.yaml missing inline 'api_key:' binding (BYOK 401 regression — see hermes.template.yaml model.api_key)"
 fi
 
+if echo "$config" | grep -q "max_turns: 30"; then
+  pass "config.yaml bounds each agent request to 30 turns by default"
+else
+  fail "config.yaml missing the default max_turns safety budget"
+fi
+
+if echo "$config" | grep -A8 '^    telegram:' | grep -q "interim_assistant_messages: false"; then
+  pass "telegram suppresses permanent interim assistant messages"
+else
+  fail "telegram must suppress interim assistant messages to avoid progress spam"
+fi
+
+if echo "$config" | grep -A8 '^    telegram:' | grep -q "streaming: false"; then
+  pass "telegram emits a final response instead of token-stream bubbles"
+else
+  fail "telegram streaming must be disabled for stable conversational delivery"
+fi
+
 # --- Open-source skills install (PERKOS_AGENT_SKILLS_B64) ---
 # Boot a second container with a skills payload: one allow-listed entry
 # (real SHA-pinned ethskills SKILL.md) + one non-allow-listed host. Assert