PR #13387: fix(telegram): log document/video send failures instead of printing to stdout (#13356)

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

Description (problem / solution / changelog)

Addresses the observability portion of #13356.

TL;DR

TelegramAdapter.send_document and send_video wrote native-send exceptions to stdout via print(...) before falling back to the base adapter. On systemd / Docker / journald-captured gateway deployments stdout isn't captured in the gateway log stream — so operators reporting "Hermes says success, Telegram received nothing" had no visible error to diagnose.

Fix: replace print with logger.error(..., exc_info=True), matching the established pattern in send_voice and send_image_file in the same file.

Root cause

gateway/platforms/telegram.py:

# send_document (line 1777)
except Exception as e:
    print(f"[{self.name}] Failed to send document: {e}")   # ← stdout, invisible
    return await super().send_document(...)                # ← fallback to text

# send_video (line 1808) — same pattern
except Exception as e:
    print(f"[{self.name}] Failed to send video: {e}")
    return await super().send_video(...)

The two adjacent native-send methods in the same file already use the correct pattern:

# send_voice (line 1701)
logger.error(
    "[%s] Failed to send Telegram voice/audio, falling back to base adapter: %s",
    self.name, e, exc_info=True,
)

# send_image_file (line 1738) — identical
logger.error(
    "[%s] Failed to send Telegram local image, falling back to base adapter: %s",
    self.name, e, exc_info=True,
)

Only send_document and send_video drifted to print.

Fix

# send_document
except Exception as e:
    logger.error(
        "[%s] Failed to send Telegram document, falling back to base adapter: %s",
        self.name, e, exc_info=True,
    )
    return await super().send_document(chat_id, file_path, caption, file_name, reply_to)

Identical change for send_video. 4 production-line delta total.

Behaviour matrix

Narrow scope — explicitly not changed

• Fallback routing. Still falls through to super().send_document(...) / super().send_video(...), matching send_voice / send_image_file. This PR only fixes observability.
• Return value. SendResult still reflects the text fallback's success, same as the sibling methods.
• Other adapters. Only Telegram had the print pattern; other platforms already use logger.
• The deeper reporter question — whether Telegram's native send returning a Message object (with message_id) for a subsequently-dropped file is also a bug — is out of scope here. With proper logging in place operators can now diagnose the actual upstream error and decide if that semantic needs changing.

Regression coverage

tests/gateway/test_telegram_documents.py gets 5 new cases (3 for send_document, 2 for send_video), leveraging caplog + capsys:

TestSendDocument:

• test_send_document_api_error_is_logged_with_exc_info — asserts an ERROR record lands in gateway.platforms.telegram logger with (1) exc_info attached, (2) exception text present, (3) adapter name in message.
• test_send_document_logs_do_not_hit_stdout — structural pin: the old "[Telegram] Failed to send document" string must not appear on stdout. Prevents regression back to print.
• test_send_document_still_invokes_base_fallback_on_error — preserved-behaviour canary: this PR only changes observability, not routing.

TestSendVideo: matching pair (..._is_logged_with_exc_info, ..._logs_do_not_hit_stdout).

4 of 4 stdout-and-logger tests fail on clean origin/main (6fb69229) with the exact symptom:

AssertionError: '[Telegram] Failed to send document' is contained here:
  [Telegram] Failed to send document: boom
AssertionError: Expected an ERROR-level log from gateway.platforms.telegram
  on send_document failure

Validation

source venv/bin/activate
python -m pytest tests/gateway/test_telegram_documents.py -q
# 36 passed

Broader Telegram suite (4 test files) → 68 passed, 0 regressions.

Pre-empted review questions

Q. Why not also remove the super() text fallback — isn't returning success=True misleading when the file didn't actually send? Maybe, but that's a deliberate scope-narrowing choice. The same "fall through to base on native failure" pattern exists in send_voice and send_image_file — changing it for Telegram specifically would break adapter symmetry and risk regressions in callers that rely on the fallback. Happy to follow up with a separate PR if the maintainer wants that behavior for Telegram.

Q. Why test both caplog and capsys? caplog pins the positive invariant (error IS logged correctly). capsys pins the negative invariant (error is NOT leaked to stdout). Together they're a two-sided guard — a future refactor that adds print back in addition to logger.error would still be caught by capsys.

Q. Is this a complete fix for #13356? For the observability portion, yes. For the reporter's deeper "success reported, file never arrives" concern, the fix here at minimum makes any raised exception diagnosable. If Telegram is returning message_id for a file that's subsequently server-side dropped, that's either a python-telegram-bot semantics issue or a message_thread_id / path-access issue that needs separate investigation — with proper logging in place operators can now surface the actual upstream error.

_{Co-authored via LLM assistance; I've reviewed every line and am responsible for correctness.}

Changed files

• gateway/platforms/telegram.py (modified, +23/-2)
• tests/gateway/test_telegram_documents.py (modified, +167/-0)

PR #13421: fix(telegram): ensure file attachments are actually delivered (fixes #13356)

• Repository: NousResearch/hermes-agent
• Author: ztexydt-cqh
• State: closed | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/13421

Description (problem / solution / changelog)

Problem

Telegram text delivery works, but file attachments report success but never arrive (#13356).

Root Cause

TelegramAdapter.send_document() caught exceptions and fell back to super().send_document() which sends text like '📎 File: {path}' - this produced a real message ID but never delivered the actual file.

Fix

• Removed fallback to text delivery in send_document, send_voice, send_image_file, send_video
• Added validation for msg.message_id in all media send methods
• send_message_tool._send_telegram() now validates that media send returns valid message_id
• Returns SendResult(success=False, error=...) on any exception instead of falling back to text

Testing

• Syntax validation passed
• Regression tests added for file send failure handling

Files Changed

• gateway/platforms/telegram.py
• tools/send_message_tool.py
• tests/tools/test_telegram_file_fix.py

Changed files

• gateway/platforms/telegram.py (modified, +851/-295)
• tests/tools/test_telegram_file_fix.py (added, +164/-0)
• tools/send_message_tool.py (modified, +550/-111)

PR #13434: fix(telegram): ensure file attachments are actually delivered (fixes #13356)

• Repository: NousResearch/hermes-agent
• Author: ztexydt-cqh
• State: closed | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/13434

Description (problem / solution / changelog)

Problem

Telegram text delivery works, but file attachments report success but never arrive (#13356).

Root Cause

TelegramAdapter.send_document() caught exceptions and fell back to super().send_document() which sends text like '📎 File: {path}' - this produced a real message ID but never delivered the actual file.

Fix

• Removed fallback to text delivery in send_document, send_voice, send_image_file, send_video
• Added validation for msg.message_id in all media send methods
• send_message_tool._send_telegram() now validates that media send returns valid message_id
• Returns SendResult(success=False, error=...) on any exception instead of falling back to text

Testing

• Syntax validation passed
• Regression tests added for file send failure handling

Files Changed

• gateway/platforms/telegram.py
• tools/send_message_tool.py
• tests/tools/test_telegram_file_fix.py

Changed files

• gateway/platforms/telegram.py (modified, +899/-304)
• tests/tools/test_telegram_file_fix.py (added, +164/-0)
• tools/send_message_tool.py (modified, +611/-120)

PR #13440: fix(telegram): ensure file attachments are actually delivered (fixes #13356)

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

Description (problem / solution / changelog)

Problem

Telegram text delivery works, but file attachments report success but never arrive (#13356).

Root Cause

TelegramAdapter.send_document() caught exceptions and fell back to super().send_document() which sends text like '📎 File: {path}' - this produced a real message ID but never delivered the actual file.

Fix

• Removed fallback to text delivery in send_document, send_voice, send_image_file, send_video
• Added validation for msg.message_id in all media send methods
• send_message_tool._send_telegram() now validates that media send returns valid message_id
• Returns SendResult(success=False, error=...) on any exception instead of falling back to text

Testing

• Syntax validation passed
• Regression tests added for file send failure handling

Files Changed

• gateway/platforms/telegram.py
• tools/send_message_tool.py
• tests/tools/test_telegram_file_fix.py

Changed files

• gateway/platforms/telegram.py (modified, +899/-304)
• tests/tools/test_telegram_file_fix.py (added, +164/-0)
• tools/send_message_tool.py (modified, +611/-120)