PR #17325: fix(telegram): stop large videos from triggering infinite model fallback (#17302)

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

Description (problem / solution / changelog)

Closes #17302.

Summary

When a Telegram video > 20 MB hits the bot, getFile() raises BadRequest("File is too big"). The current handler catches the exception, logs a warning, and falls through to handle_message(event) with an effectively empty event — the agent then burns through every fallback model (15+ retries in the reporter's logs) trying to respond to nothing.

This PR fixes it with three layered defenses, mirroring the size-check pattern that the non-video document branch already uses:

1. Pre-check file_size before downloading

Both the native msg.video branch and the video-as-document branch now verify file_size <= 20 MB before calling get_file(). Oversize / unverifiable videos short-circuit with a user-visible message ("Telegram's Bot API limits file downloads to 20 MB…") and message_type=VIDEO. The agent gets a meaningful event instead of a blank one.

2. Trap "File is too big" inside the except block

For forwarded-video / edited-message edge cases where file_size lies, the BadRequest is now caught at runtime and event.text is set to an explanatory message instead of being left blank. This is the surgical fix that prevents the fallback storm even when the pre-check is bypassed.

3. Optional opt-out: telegram.extra.ignore_videos: true

When set, video messages (native and video/* MIME documents) are dropped at the top of _handle_media_message, before any work is done. Other media (PDFs, photos, voice, audio) is unaffected.

Why not the issue's exact diff

The issue's proposed diff calls self._send_safe_message(...) which doesn't exist in this codebase (only self._bot.send_message(...) does). I kept the spirit of the suggestion — the friendly text message — but routed it through the existing event.text + handle_message() path that the document handler already uses for "Unsupported document type" and "too large or unverifiable", so the fix is consistent with the surrounding code rather than introducing a new send pattern.

Tests

Added 8 new tests in tests/gateway/test_telegram_documents.py::TestVideoDownloadBlock:

• test_oversize_native_video_short_circuits_with_friendly_text
• test_unverifiable_native_video_size_short_circuits (parity with the existing document file_size=None security fix)
• test_oversize_video_document_short_circuits
• test_native_video_get_file_too_big_does_not_send_blank_event
• test_video_document_get_file_too_big_does_not_send_blank_event
• test_ignore_videos_config_skips_native_video
• test_ignore_videos_config_skips_video_documents
• test_ignore_videos_does_not_block_pdfs

The existing _make_video() helper now defaults file_size=1024 so the prior happy-path test still passes through the new gate.

$ python -m pytest tests/gateway/test_telegram_documents.py -q
............................................                          [100%]
44 passed in 3.50s

python3 -c "import ast; ast.parse(open('gateway/platforms/telegram.py').read())" clean.

Out of scope

The reporter's _send_safe_message reply-via-Telegram pattern is more invasive than needed; the agent-event path is sufficient and consistent with how the document handler already communicates blocked uploads. Happy to add a direct reply if maintainers prefer it.

Changed files

• gateway/platforms/telegram.py (modified, +82/-4)
• tests/gateway/test_telegram_documents.py (modified, +120/-1)