PR #28723: fix(gateway): extend follow-up grace to WeChat/WeCom + bump default to 5s (#28417)

• Repository: NousResearch/hermes-agent
• Author: xxxigm
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/28723

Description (problem / solution / changelog)

What does this PR do?

#28417 reports that on Telegram and WeChat (微信), a single Q&A "自动自动中断" — auto-interrupts before the agent has finished its reply, takes a long time to recover, then breaks again on retry.

Root-cause walk-through (see tests/gateway/test_messaging_followup_grace.py for the contract pinned by this PR):

1. The runner's default busy_input_mode is "interrupt" (gateway/run.py:1411). Any second user text that arrives while an agent task is running for that session_key fires interrupt_event.set(), aborts the run, and the partial reply is suppressed via the stale-response path in gateway/platforms/base.py:3143-3156.
2. To stop normal user behavior (typo correction, IME segmentation, voice-to-text fixups) from tripping that interrupt, there's a 3-second "follow-up grace window" in _handle_message that merges the second message into the pending buffer instead.
3. But that grace was Telegram-only (source.platform == Platform.TELEGRAM). WeChat had no grace at all — every burst follow-up interrupted the run. That's the exact asymmetry that made #28417 hit WeChat just as hard as Telegram.
4. The 3-second default is also too short for normal mobile bursts: Chinese IMEs and voice-to-text often emit a second short text 2–4s after the first.

Fix (smallest defensible change):

• Generalize the grace window to a _FOLLOWUP_GRACE_PLATFORMS frozenset covering Telegram, Weixin, WeCom, WeCom callback — the four platforms in scope for the burst-follow-up pattern that triggered this bug. Slack/Discord/WhatsApp/Feishu intentionally stay on the legacy path; future widenings should be an explicit edit of the set, not a drive-by.
• New env var HERMES_GATEWAY_FOLLOWUP_GRACE_SECONDS is the canonical knob. The legacy HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS is still honoured as a fallback so existing deployments that tuned it don't see their value reset.
• Default bumped from 3.0 → 5.0 seconds. Still well below "the user typed a fresh question" territory, but wide enough to swallow IME / voice-to-text bursts.
• Invalid env values fail open to the default instead of crashing request handling; negative values clamp to zero.
• Debug log now names the actual platform instead of always saying "Telegram", which had hidden the WeChat case in production logs.

The fix touches one branch in _handle_message plus two new static helpers — the rest of the busy-session machinery is unchanged.

Related Issue

Fixes #28417

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✅ Tests (adding or improving test coverage)
• 📝 Documentation update

Changes Made

• gateway/run.py —
  • Replace the inlined Telegram-only branch in _handle_message with a call to two new static helpers: _platform_has_followup_grace() (checks the _FOLLOWUP_GRACE_PLATFORMS frozenset of TELEGRAM / WEIXIN / WECOM / WECOM_CALLBACK) and _messaging_followup_grace_seconds() (resolves env vars, fails open on bad input, clamps negative values to zero).
  • Update the debug log to include the actual platform name.
  • 75 added / 7 removed lines.
• tests/gateway/test_messaging_followup_grace.py — new 267-line test module with 20 tests over four axes:
  • Platform coverage — Telegram + Weixin + WeCom + WeCom callback all queue-without-interrupt within the window.
  • Negative coverage — Slack stays on the legacy path so this PR doesn't accidentally widen scope.
  • Timing semantics — outside the window, the grace branch defers to normal busy-session handling; 0 disables the window entirely.
  • Env var resolution — generalised wins over legacy, legacy still honoured, default 5.0, malformed values fall back, negative values clamp.
  • Parametrised membership test over 8 platforms so future additions are an explicit fail-the-test diff.
• website/docs/reference/environment-variables.md —
  • Add a row for HERMES_GATEWAY_FOLLOWUP_GRACE_SECONDS linking to #28417.
  • Fix the existing HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS description, which incorrectly said the knob delayed outbound messages "to avoid racing the last stream chunk" — it actually controls the inbound follow-up merge window.

How to Test

# New regression suite.
scripts/run_tests.sh tests/gateway/test_messaging_followup_grace.py -q
# Expected: 20 passed in ~1s.

# Adjacent suites that exercise the surrounding busy-session paths.
scripts/run_tests.sh \
  tests/gateway/test_telegram_photo_interrupts.py \
  tests/gateway/test_active_session_text_merge.py \
  tests/gateway/test_busy_session_ack.py \
  tests/gateway/test_command_bypass_active_session.py \
  -q
# Expected: 58 passed (no regressions).

Manual reproduction (Telegram or WeChat):

1. Start a long-running agent turn (e.g. ask for a multi-paragraph summary).
2. Within 3–5s of starting, send a short follow-up ("oops, in English please").
3. Before this PR (WeChat): the run is interrupted, the partial answer is suppressed, the bot starts over from scratch with the merged text — exactly the symptom in #28417.
4. After this PR: the follow-up is merged into pending and the in-flight run completes uninterrupted; the merged context is consumed on the next turn.

Checklist

Code

• My commit messages follow Conventional Commits (fix(gateway):, test(gateway):, docs(env):)
• I searched for existing PRs — no duplicate
• My PR contains only changes related to this fix
• I've run scripts/run_tests.sh tests/gateway/test_messaging_followup_grace.py -q (20 passed)
• I've added regression tests covering the asymmetry that caused the bug
• I've tested on my platform: macOS 15.x (darwin 24.6.0)

Documentation & Housekeeping

• I've updated relevant documentation (website/docs/reference/environment-variables.md — added the new knob, fixed the misleading existing description)
• N/A — no config.yaml schema changes (env-only knob, with documented config.yaml route via display.busy_input_mode already present)
• N/A — no architecture or workflow change requiring CONTRIBUTING.md / AGENTS.md updates
• I've considered cross-platform impact — pure Python in a _handle_message branch, no platform-specific syscalls. The fix runs identically on Linux/macOS/Windows.
• N/A — no tool description/schema changes

Changed files

• gateway/run.py (modified, +75/-7)
• tests/gateway/test_messaging_followup_grace.py (added, +267/-0)
• website/docs/reference/environment-variables.md (modified, +2/-1)