Summary

Two related bugs in gateway/platforms/telegram.py cause Telegram document attachments to silently fail or, worse, get mistakenly delivered to the agent as if the user typed the gateway's own error string. Both are in the document-handling block at roughly lines 3258-3322 of telegram.py (current main).

Bug 1: Unsupported document types are routed to the agent as fake user messages

Where

gateway/platforms/telegram.py lines ~3265-3273:

if ext not in SUPPORTED_DOCUMENT_TYPES:
    supported_list = ", ".join(sorted(SUPPORTED_DOCUMENT_TYPES.keys()))
    event.text = (
        f"Unsupported document type '{ext or 'unknown'}'. "
        f"Supported types: {supported_list}"
    )
    logger.info("[Telegram] Unsupported document type: %s", ext or "unknown")
    await self.handle_message(event)
    return

What happens

When a user sends an unsupported file (e.g. .epub):

1. The gateway sets event.text to "Unsupported document type '.epub'. Supported types: .cfg, .csv, ..."
2. It calls self.handle_message(event) — which routes the event into the agent pipeline as if it were a normal user message
3. From the agent's perspective, the user just sent a message saying "Unsupported document type '.epub'..." — there is no metadata indicating this is a gateway-generated error, not user content

Observed impact

In a real Telegram session 2026-05-09, a .epub was attached. The agent received turns where inbound message: ... msg="Unsupported document type '.epub'..." appeared in gateway.log as if the user had typed it. The agent had no way to know:

• The actual user intent was to share an attachment
• The error was generated by the gateway, not typed by the user
• The user's next messages ("ffs, it was attached as a .MD file") referred to a previous attempt the gateway never surfaced as anything except an error string

The agent then went in circles asking "where is the file?" because it had no signal that an attempt-to-attach had occurred at all — only a string that looked like the user complaining about an unsupported type.

Proposed fix

The user-facing message about unsupported types should be sent back to the user via the Telegram channel (a reply message), not routed into the agent pipeline. Two minimum changes:

1. Use a Telegram reply (update.message.reply_text(...)) to inform the user, instead of forging an event.text value
2. Either return without calling handle_message, OR call handle_message with event.text = None and set a structured flag like event.gateway_notice = "unsupported_document_type" so the agent can recognize it as a gateway-generated event distinct from user content

Bonus: include the original filename in the reply so the user knows which file got rejected when they sent multiple in close succession.

Bug 2: Cache failures are silently swallowed; agent receives an empty/broken event

Where

gateway/platforms/telegram.py lines ~3286-3315:

# Download and cache
file_obj = await doc.get_file()
doc_bytes = await file_obj.download_as_bytearray()
raw_bytes = bytes(doc_bytes)
cached_path = cache_document_from_bytes(raw_bytes, original_filename or f"document{ext}")
mime_type = SUPPORTED_DOCUMENT_TYPES[ext]
event.media_urls = [cached_path]
event.media_types = [mime_type]
logger.info("[Telegram] Cached user document at %s", cached_path)

# For text files, inject content into event.text (capped at 100 KB)
# ... text injection block ...

except Exception as e:
    logger.warning("[Telegram] Failed to cache document: %s", e, exc_info=True)

What happens

The broad except Exception (currently catching httpx.ConnectError and friends from Telegram CDN download failures) logs a warning and falls through — no return, no user-facing message, no agent-visible signal. The function then proceeds to line ~3322's await self.handle_message(event) with:

• event.media_urls = [] (never set, since the cache call failed before line 3292)
• event.media_types = [] (same reason)
• event.text = whatever caption the user typed (often empty)
• No flag indicating an attempted-but-failed attachment

Observed impact

In the same 2026-05-09 session, a .md attachment hit httpx.ConnectError at the cache step (gateway log: WARNING gateway.platforms.telegram: [Telegram] Failed to cache document: httpx.ConnectError:). The user thought the file had been delivered. The agent received an empty event with no media and no text. From there:

• Agent had no visible signal an attachment was even attempted
• Agent's earlier wrong claim ("Telegram doesn't deliver attachments to me") was reinforced
• The user had to escalate frustration multiple turns before the agent stumbled onto the cache directory and root-caused the failure by reading gateway.log directly

This is a "silent data loss" bug class. The user thinks they delivered something; the agent thinks nothing happened; the only record is a warning buried in the log.

Proposed fix

Three independent improvements (any one closes the silent-loss):

1. Send a user-facing error reply on cache failure: await update.message.reply_text(f"⚠️ Couldn't download your attachment ({e.__class__.__name__}). Please retry.") before the function returns.
2. Retry with backoff before giving up: Telegram CDN flakes are transient; one retry with a 2-3s sleep would catch most. The httpx ConnectError observed in the affected session was a known network blip (the same gateway log shows two other ConnectErrors against api.telegram.org earlier the same day).
3. Surface the failure to the agent as structured signal: set event.gateway_error = {"type": "document_cache_failure", "exception": str(e), "original_filename": original_filename} so the agent can react ("I see Telegram tried to deliver an attachment but the cache failed — please retry") instead of silently treating the message as content-less.

Ideally do all three: reply to the user immediately, retry once, and surface the failure as structured signal even after retry exhaustion.

Combined repro

In a Telegram chat with a Hermes gateway:

1. Attach an unsupported file type (e.g., .epub). Observe agent receives the gateway's error text as if the user typed it.
2. Attach a .md file during a brief network blip to api.telegram.org (or simulate by inducing httpx.ConnectError at cache step). Observe the agent receives an empty event with no signal that an attachment was attempted.

Both bugs were observed back-to-back in a real session 2026-05-09 ~23:40-23:50 PT.

Severity

Medium-high. The user-perceived effect is "the agent is broken / lost my file / pretends I didn't send anything." This is exactly the failure mode that erodes user trust in the gateway. The bugs interact: Bug 1 made the agent confused about which files the user was referencing in subsequent turns, which fed into Bug 2's silent loss because the agent had no consistent picture of what files had even been attempted.

Out of scope for this issue

• Adding .epub to SUPPORTED_DOCUMENT_TYPES. That's a separate feature decision.
• Restructuring MessageEvent to have a first-class gateway_notice / gateway_error field. The proposed fix can use existing event attributes; a structured-event refactor is a separate concern.
• Other platforms (Discord, Slack, Matrix). The fixes here are Telegram-specific. Other platforms may have similar shapes worth auditing as follow-ups.

Source

Discovered during a real user session 2026-05-09. Gateway log excerpt:

2026-05-09 23:40:01,432 INFO gateway.platforms.telegram: [Telegram] Unsupported document type: .epub
2026-05-09 23:40:02,473 INFO gateway.run: inbound message: platform=telegram user=Richard Murillo chat=8244195464 msg="Unsupported document type '.epub'. Supported types: .cfg, .csv, .js"
2026-05-09 23:49:08,615 WARNING gateway.platforms.telegram: [Telegram] Failed to cache document: httpx.ConnectError:
2026-05-09 23:50:54,871 INFO gateway.run: inbound message: platform=telegram user=Richard Murillo chat=8244195464 msg='ffs, it was attached as a .MD file'

The agent's session loop spent multiple turns confused about whether attachments had been delivered, what file the user was referencing, and why earlier "messages" appeared to be from the user but contained gateway-generated error text.