What does this PR do?

This PR fixes a Telegram document delivery bug where Hermes could fall back to sending plain text like 📎 File: / instead of a real attachment.

Previously, if TelegramAdapter.send_document() received a path that existed but was not a regular file (for example /), the upload path would raise an exception and fall back to the base adapter's text-only document sender. That made delivery look successful even though no actual file was sent.

This change fixes that by:

• rejecting existing non-file paths before attempting upload
• returning an explicit failure when Telegram document upload fails
• preventing fallback to misleading plain-text file-path messages

This is the right approach because it preserves correctness: a failed document upload should fail explicitly rather than pretending success with a text fallback.

After this fix, Hermes can successfully send real document attachments through Telegram when given a valid file path, and it now fails explicitly instead of falling back to misleading plain-text file path messages.

Related Issue

Fixes #13356

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• Updated gateway/platforms/telegram.py
  • added _invalid_media_path_error(...)
  • added os.path.isfile(...) validation before Telegram document upload
  • changed document-send exception handling to return SendResult(success=False, ...)
  • replaced print(...) fallback behavior with structured logging via logger.error(...)
• Updated tests/gateway/test_telegram_documents.py
  • changed the Telegram API error test to assert explicit failure instead of text fallback
  • added a regression test for directory / non-regular-file paths

How to Test

1. Run:

   python -m pytest tests/gateway/test_telegram_documents.py -q -o 'addopts='

2. Verify the test suite passes.
3. Manually verify behavior:
   • send a valid PDF through the Telegram adapter and confirm it is delivered as a real document
   • call send_document() with / or another directory path and confirm it returns a real failure such as:

     File path is not a file: /
     

   • confirm Hermes no longer sends fallback text like:

     📎 File: /
     

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: Docker container / Telegram gateway validation path

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

Test command:

python -m pytest tests/gateway/test_telegram_documents.py -q -o 'addopts='

Result:

37 passed in 4.73s

Manual verification:

• valid PDF delivery through Telegram adapter succeeded
• invalid path / now returns:

File path is not a file: /

• fallback text delivery like 📎 File: / is no longer used for this failure case