PR #25051: fix(gateway): verify streamed final before suppressing send

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

Description (problem / solution / changelog)

What does this PR do?

Fixes a Telegram gateway streaming failure where a partial streamed message can remain visible while the normal final send is suppressed.

Root cause: the gateway treated GatewayStreamConsumer.final_response_sent=True as enough proof that the final assistant reply had reached the user. In some interrupt/cancellation paths, that flag can be set after a best-effort edit of only the currently accumulated partial text. When the agent later returns the complete final_response, the gateway suppresses the normal final send and the user is left with the incomplete partial message.

This PR makes final-send suppression require an exact final-text confirmation:

• GatewayStreamConsumer now records the text that was actually confirmed as the streamed final reply.
• gateway/run.py suppresses the normal final send only when the stream consumer confirms that the streamed text matches the current final_response.
• Partial/cancelled streamed edits no longer count as complete final delivery for a longer final response.

Why this is still valuable with related PRs/issues:

• #18017 is related, but it is a broad open branch with very large unrelated gateway/agent churn. This PR is a narrow fix against current main.
• #16668 is the same bug family, but it covered the opposite visible symptom (partial + duplicate final). #25010 is partial + final suppressed.
• This PR adds the missing exact-text guard, so the gateway no longer relies on a coarse boolean that can be true for partial delivery.

Related Issue

Fixes #25010

Related to #18017, #16668, #13542, and #10747.

Type of Change

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

Changes Made

• Added confirmed-final text tracking to gateway/stream_consumer.py.
• Added GatewayStreamConsumer.final_response_matches(...) so callers can distinguish exact final delivery from partial streamed output.
• Updated gateway/run.py final-send suppression to use exact streamed-final confirmation instead of final_response_sent alone.
• Added regression coverage in tests/gateway/test_duplicate_reply_suppression.py for the mismatched streamed-final case.
• Extended cancellation coverage in tests/gateway/test_stream_consumer.py to verify that a partial cancellation edit does not match a longer final reply.

How to Test

1. Reproduce the failure mode in unit form: a stream consumer reports final_response_sent=True, but its confirmed streamed text is only "partial" while the gateway final response is "partial plus final".
2. Verify the gateway does not mark already_sent=True for that mismatch.
3. Run the focused gateway tests:

$ PYTHONPATH=$PWD /tmp/hermes-provider-refresh-venv/bin/python -m pytest -o addopts= tests/gateway/test_stream_consumer.py tests/gateway/test_duplicate_reply_suppression.py
============================= test session starts ==============================
platform linux -- Python 3.13.9, pytest-9.0.2, pluggy-1.6.0
rootdir: /mnt/d/hermes-agent
configfile: pyproject.toml
plugins: split-0.11.0, xdist-3.8.0, asyncio-1.3.0, anyio-4.13.0
asyncio: mode=Mode.STRICT, debug=False, asyncio_default_fixture_loop_scope=None, asyncio_default_test_loop_scope=function
collected 112 items

tests/gateway/test_stream_consumer.py .................................. [ 30%]
.......................................................                  [ 79%]
tests/gateway/test_duplicate_reply_suppression.py ...................... [ 99%]
.                                                                        [100%]

============================= 112 passed in 12.31s =============================

Additional syntax check:

$ PYTHONPATH=$PWD /tmp/hermes-provider-refresh-venv/bin/python -m py_compile gateway/run.py gateway/stream_consumer.py

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Ubuntu/WSL

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Screenshots / Logs

N/A. This is gateway delivery-state logic covered by focused unit tests.

Changed files

• gateway/run.py (modified, +11/-3)
• gateway/stream_consumer.py (modified, +32/-13)
• tests/gateway/test_duplicate_reply_suppression.py (modified, +12/-0)
• tests/gateway/test_stream_consumer.py (modified, +2/-1)