Closes #9291

Summary

Fixes all three issues reported in #9291. Using the repro shape from
that issue:

Here is a summary of the catalog.

MEDIA:/path/item_a_view1.png
Item A — view 1
MEDIA:/path/item_a_view2.png
Item A — view 2
MEDIA:/path/item_b_view1.png
Item B — view 1
MEDIA:/path/item_b_view2.png
Item B — view 2

MEDIA:/path/featured.png
Featured item

After this PR the Telegram gateway produces:

• One text-only message: Here is a summary of the catalog.
• One album of four photos, each with its own caption.
• One single photo with its own caption.

Changes

1. Reliable Telegram albums (issue #9291 §1)

TelegramAdapter.send_media_group() previously opened local files via
open(fp, "rb"). When the MarkdownV2 attempt failed, the retry path
could not cleanly reuse the handles, and the call fell through to the
base-class individual-send fallback — while still returning
success=True.

The primary and retry paths now both use file_path.read_bytes(), so
the bytes are independently reusable across attempts. The
individual-send fallback now emits an explicit warning when reached,
so silent degradation is observable.

2. No caption leakage in streamed message (issue #9291 §2)

In streaming mode the full response (caption lines included) is
streamed as a single text message before media delivery runs. The
previous behaviour left those caption lines visible in the prose.

_deliver_media_from_response() now detects the TextBlock +
captioned-media case and edits the streamed message down to the
TextBlock content only, stripping caption lines. Pure-media
responses keep the original delete-and-replace behaviour.

3. Per-item captions within a single album (issue #9291 §3)

_parse_content_blocks() is reworked so that:

• A caption line immediately after a MEDIA: line attaches to that
  item's caption, keeping items in the same MediaGroupBlock.
• A blank line after caption text ends the current group.
• Trailing caption after the last MEDIA: attaches to the LAST item
  when the group uses per-item captions, or to the FIRST item when no
  per-item captions are present — preserving the legacy group-level
  caption shape exactly.

This lets an agent emit an arbitrary mix of per-item captions, a
shared trailing caption, or no captions at all, without accidentally
splitting one intended album into multiple groups, and without
changing the observed behaviour of any pre-existing response shape.

Structural Additions

• ContentBlock dataclasses (TextBlock, ImageBlock,
  MediaGroupBlock, MediaGroupItem) in gateway/platforms/base.py.
• Default send_media_group() fallback on BasePlatformAdapter so
  adapters without native album support degrade gracefully to
  sequential single sends.
• StreamConsumer.response_message_id property exposes the
  already-streamed message ID so the deliverer can edit it in place.

Prompt-Side Adoption (added in this PR)

The delivery layer accepts the per-item caption shape, but getting
non-Anthropic models to produce it reliably needs prompt guidance.
agent/prompt_builder.py now appends a shared _MEDIA_GROUP_RULES
block to the telegram, whatsapp, discord, slack, signal,
and bluebubbles platform hints. The block is example-first, lists
the split/merge pitfalls explicitly, and points at the
telegram-media-group-captions skill for complex cases.

weixin/wecom are intentionally skipped — native album semantics
there differ from Telegram/Signal and warrant a separate pass.

Verified on live Telegram

Tests

tests/agent/test_prompt_builder.py::TestMediaGroupRules adds 92
cases covering: rule presence on each included platform, absence on
weixin/email, the exact example block, and the bullet rules.
Full test_prompt_builder suite: 150/150 green.

Behavioural Side-Effect Worth Calling Out

Refactoring the caption path through a shared _prepare_caption()
helper means all Telegram send_* methods (send_photo,
send_video, send_document, send_voice, send_audio,
send_animation, etc.) now attempt MarkdownV2 formatting with a
plain-text fallback, where previously they sent captions as plain text
only. This is a deliberate widening — it makes caption behaviour
consistent across all Telegram sends — but it is broader than "just
albums", so flagging it here for reviewer awareness.

Tests

• Parser: 13 tests in tests/gateway/test_platform_base.py cover
  per-item captions, legacy group-level trailing caption attaching to
  the first item, mixed per-item + trailing caption attaching to the
  last item, blank-line group separation, auto-split at Telegram's
  10-item album limit, URL-based media, and the FILE: document
  prefix.
• Streaming regression: new AlreadySentAgent stub and tests in
  tests/gateway/test_run_progress_topics.py exercise the streaming
  delivery path end-to-end.
• Affected suite: test_platform_base.py +
  test_run_progress_topics.py → 105 passed, 0 failed.
• Full suite: 11,234 passed, 0 new failures attributable to this
  PR (tests/ baseline on main has 79 pre-existing failures,
  unchanged by this PR — verified by running the full suite on HEAD~1
  and HEAD and diffing the failure sets).

Manual Testing

Verified on a live Telegram deployment with a multi-item product
catalogue response (multiple items × multiple views). Confirmed:

• Album forms correctly with each item's caption attached.
• Streamed prose message ends up with intro text only.
• Single trailing image with caption still works.
• FILE:MEDIA: prefix still delivers as a document.
• MarkdownV2 in captions (**bold**, ||spoiler||) renders correctly
  in single images and in album items.

Files Changed