feat(relay): Phase 2 media parity — send_media egress + inbound media localization

[benbarclay]

Relay Phase 2 — media parity (gateway side)

Gateway half of the Phase 2 media pair: the RelayAdapter gains native media sends (images, voice notes, videos, documents) and inbound media localization, closing the gap where hosted/relay chats could only exchange text while every native adapter shipped attachments. Media crosses the wire by reference, never by value. Additive within contract_version 1.

Cross-repo pair: NousResearch/gateway-gateway#173 (connector side: re-host plane, four ingress lanes, four platform send_media senders).

gateway/relay/media.py — the media-plane client

• upload(path) → POST {connector}/relay/media (raw bytes, Content-Type + X-Media-Filename), returns the /relay/media/{id} reference a send_media op names. How a locally-generated artifact (image_generate output, TTS voice note, a document) crosses to the connector without the gateway needing a public URL.
• download(url) → GET a re-hosted inbound attachment to a local temp file (extension derived from content-disposition/mime — vision/file tools sniff by extension).
• Same connector base URL the WS dials, same per-gateway signed bearer as the upgrade (make_upgrade_token, auth.py) — zero new configuration. stdlib urllib in a thread executor (no new deps, same posture as _post_provision). 25MB cap mirrors the connector's MEDIA_MAX_BYTES.

RelayAdapter egress — five overrides, one op

send_image / send_image_file / send_voice / send_video / send_document route through a single _send_media helper: local paths upload first, public URLs pass through; caption rides content; the same scope/user egress discriminators as send ride metadata (the connector's egress guard resolves tenants identically).

Progressive enhancement, never a regression: every lane is gated on supported_ops advertising send_media (legacy connectors — including the empty-ops legacy set — never see the op) and every failure (no client, failed upload, connector decline, transport error) returns to the base-class fallback, which still delivers the caption/notice and never leaks local paths into chat.

Inbound localization

_on_inbound now localizes media_urls before handle_message: connector re-hosts are downloaded with the per-gateway bearer, entries become local temp paths (native-adapter parity — an authenticated URL is useless to downstream consumers). Dead re-host refs are dropped; public URLs survive a missing client. Best-effort per entry; never blocks or loses the message.

Contract doc

docs/relay-connector-contract.md §4: send_media op row + the media ingress/egress semantics (upload route, capability-URL re-host reads, TTL, kind mapping) — replaces the "deferred to a later contract revision" placeholder.

Deploy order

Connector first (it must advertise send_media and mount /relay/media); a gateway on this PR against an older connector simply keeps today's text fallbacks (op-gated). No new env vars or config.

Verification

• tests/gateway/relay/test_relay_media.py — 15 new tests: kind mapping across all five overrides, upload-first path handling (local path never on the wire), op gating (explicit + legacy-empty ops), connector-decline and upload-failure fallbacks (no path leak in fallback text), scope metadata on send_media, inbound localization matrix (re-host localized / dead ref dropped / public kept without client), media_base_url derivation, client credential gating, oversize/missing upload rejection.
• Full relay suite: 235 passed (tests/gateway/relay/, includes contract-doc conformance + the sheds-crypto scan against the new module).
• Wide tests/gateway/ sweep: 11,076 passed; the 44 failures are pre-existing on main (reproduced identically on the main checkout, none in relay files; the relay suite + media tests are 259/259 green in combination runs).

[github-actions]

૮ >ﻌ< ა ci review

_{ran on 4d7fb3f}

all good!