Summary

gateway/platforms/telegram.py builds its HTTPXRequest without passing media_write_timeout, so all media uploads (send_video, send_document, large send_photo, etc.) from the Gateway path fall back to python-telegram-bot's default of 20.0s. This makes large-file replies via the bot fail with WriteTimeout even when the user sets HERMES_TELEGRAM_HTTP_MEDIA_WRITE_TIMEOUT — that env var is never read on the Gateway path.

The sibling code path in tools/send_message_tool.py (LLM tool calls) already handles this correctly with a 300s default.

Affected version

• hermes-agent v2026.5.7-26-gfaa13e49f (0.13.0), commit faa13e49f
• python-telegram-bot==22.7 (HTTPXRequest default: media_write_timeout=20.0)

Reproduction

1. Configure Telegram bot, install gateway, ask the bot anything that triggers a media reply with a file >~10MB on a non-symmetric uplink.
2. Observe WriteTimeout / httpx.WriteTimeout in journalctl --user -u hermes-gateway -f.
3. Set HERMES_TELEGRAM_HTTP_MEDIA_WRITE_TIMEOUT=600 in ~/.hermes/.env, restart gateway → same failure, because the env var is never bound on the Gateway path.

Root cause

gateway/platforms/telegram.py:936-942:

request_kwargs = {
    "connection_pool_size": _env_int("HERMES_TELEGRAM_HTTP_POOL_SIZE", 512),
    "pool_timeout": _env_float("HERMES_TELEGRAM_HTTP_POOL_TIMEOUT", 8.0),
    "connect_timeout": _env_float("HERMES_TELEGRAM_HTTP_CONNECT_TIMEOUT", 10.0),
    "read_timeout": _env_float("HERMES_TELEGRAM_HTTP_READ_TIMEOUT", 20.0),
    "write_timeout": _env_float("HERMES_TELEGRAM_HTTP_WRITE_TIMEOUT", 20.0),
}
# media_write_timeout is missing → HTTPXRequest defaults to 20.0

Compare with tools/send_message_tool.py:702-708, which does it right:

_media_write_timeout = _env_float("HERMES_TELEGRAM_HTTP_MEDIA_WRITE_TIMEOUT", 300.0)
_request = HTTPXRequest(
    write_timeout=_write_timeout,
    connect_timeout=_connect_timeout,
    read_timeout=_read_timeout,
    pool_timeout=_pool_timeout,
    media_write_timeout=_media_write_timeout,
)

Note: write_timeout and media_write_timeout are independent in PTB — bumping write_timeout does not affect media uploads, so there is no env-only workaround currently.

Proposed fix (one-line)

Add the missing key to the Gateway's request_kwargs so it stays in sync with the tool path:

request_kwargs = {
    "connection_pool_size": _env_int("HERMES_TELEGRAM_HTTP_POOL_SIZE", 512),
    "pool_timeout": _env_float("HERMES_TELEGRAM_HTTP_POOL_TIMEOUT", 8.0),
    "connect_timeout": _env_float("HERMES_TELEGRAM_HTTP_CONNECT_TIMEOUT", 10.0),
    "read_timeout": _env_float("HERMES_TELEGRAM_HTTP_READ_TIMEOUT", 20.0),
    "write_timeout": _env_float("HERMES_TELEGRAM_HTTP_WRITE_TIMEOUT", 20.0),
    "media_write_timeout": _env_float("HERMES_TELEGRAM_HTTP_MEDIA_WRITE_TIMEOUT", 300.0),
}

Same default as the tool path (300s) keeps behavior consistent across both code paths and respects the env override.

Happy to send a PR if helpful.