adapter.py 118 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305
  1. """RelayAdapter — one generic gateway adapter fronted by the connector. EXPERIMENTAL.
  2. A single ``BasePlatformAdapter`` subclass that receives a ``CapabilityDescriptor`` at
  3. handshake (which platform it fronts, which capabilities to advertise) and delegates
  4. all wire I/O to an injected transport. There is NO per-platform gateway code: only
  5. the connector knows "this chat_id maps to a Discord channel"; the gateway sees an
  6. ordinary ``MessageEvent`` in and calls ``adapter.send`` out. Transport protocol and
  7. descriptor schema may change without a deprecation cycle until >=2 Class-1 platforms
  8. validate them.
  9. """
  10. from __future__ import annotations
  11. import asyncio
  12. import logging
  13. import re
  14. import secrets
  15. import time
  16. from collections import OrderedDict
  17. from functools import partial
  18. from typing import Any, Awaitable, Callable, Dict, NamedTuple, Optional, Tuple, Union
  19. from gateway.config import Platform, PlatformConfig
  20. from gateway.platforms.base import (
  21. BasePlatformAdapter, ExecApprovalPrompt, SendResult,
  22. )
  23. from gateway.platforms.event import ProcessingOutcome
  24. from agent.i18n import t
  25. from gateway.relay.adapter_discord_interaction import RelayDiscordInteractionMixin
  26. from gateway.relay.descriptor import CapabilityDescriptor
  27. from gateway.relay.egress import (
  28. EGRESS_DECLINE_CODE,
  29. decline_error,
  30. is_egress_decline,
  31. log_decline,
  32. )
  33. from gateway.relay.media import RelayMediaClient
  34. from gateway.relay.transport import RelayTransport
  35. from datetime import UTC
  36. logger = logging.getLogger(__name__)
  37. # Native admission refusals a redelivery cannot change (sender, route or payload).
  38. _PERMANENT_REFUSALS = frozenset({'permission_denied', 'invalid_params', 'admission_conflict',
  39. 'profile_mismatch', 'not_found'})
  40. class _MediaNotDelivered(NamedTuple):
  41. """The send_media lane was available but a local file never reached the platform."""
  42. reason: str
  43. # The drain-path going-idle ACK budget must stay strictly under the runner's
  44. # default adapter disconnect timeout (5s) or cancellation fires before
  45. # transport.disconnect() and leaves the websocket open. With transport teardown
  46. # budgets of 1s each for supervisor, reader and ws.close, the drain stays <5s.
  47. _RELAY_GO_IDLE_ON_DISCONNECT_TIMEOUT_S = 2.0
  48. _RELAY_REVOCATION_MONITOR_TEARDOWN_TIMEOUT_S = 1.0
  49. # Link detection for the fresh-final unfurl route: raw URLs, Slack mrkdwn links
  50. # and markdown links. Permissive on purpose — a false positive costs one fresh
  51. # (non-edited) final; a false negative silently loses the preview.
  52. _URL_RE = re.compile(r"https?://|<https?:|\]\(https?:")
  53. # Already-answered prompt ids to remember so a duplicate answer (double tap or
  54. # connector redelivery) reads as a repeat, not a stale prompt.
  55. _RESOLVED_PROMPT_MEMORY = 256
  56. _TRUTHY = {"1", "true", "yes", "on"}
  57. _FALSY = {"0", "false", "no", "off"}
  58. _SLACK = Platform.SLACK.value
  59. # Prompt option id -> in-channel ack label (the option set doubles as the choice allowlist).
  60. _EXEC_APPROVAL_LABELS = {
  61. "once": "✅ Approved once",
  62. "session": "✅ Approved for session",
  63. "always": "✅ Approved permanently",
  64. "deny": "❌ Denied",
  65. }
  66. _SLASH_CONFIRM_LABELS = {"once": "✅ Approved once", "always": "🔒 Always approve", "cancel": "❌ Cancelled"}
  67. def _utf16_len(text: str) -> int:
  68. """Count UTF-16 code units (Telegram's length unit)."""
  69. return len(text.encode("utf-16-le")) // 2
  70. _LEN_FNS: dict[str, Callable[[str], int]] = {"chars": len, "utf16": _utf16_len}
  71. def _send_result(result: dict[str, Any], **extra: Any) -> SendResult:
  72. """Project a connector ``outbound_result`` dict onto a SendResult."""
  73. return SendResult(
  74. success=bool(result.get("success")), message_id=result.get("message_id"),
  75. error=result.get("error"), **extra,
  76. )
  77. def _event_ids(event) -> tuple[Optional[str], Optional[str]]:
  78. """(message_id, chat_id) of an inbound event; message_id lives on the event, falls back to source."""
  79. message_id = getattr(event, "message_id", None) or getattr(event.source, "message_id", None)
  80. return message_id, getattr(event.source, "chat_id", None)
  81. def _profile_from_session_key(session_key: str) -> Optional[str]:
  82. """Named profile encoded in an ``agent:<ns>:...`` session key; None for the legacy ``agent:main``
  83. namespace (single-profile gateway) so the wire frame stays byte-identical there."""
  84. parts = (session_key or "").split(":")
  85. if len(parts) < 2 or parts[0] != "agent" or not parts[1]:
  86. return None
  87. from gateway.session import profile_from_session_key_namespace
  88. profile = profile_from_session_key_namespace(parts[1])
  89. return None if profile == "default" else profile
  90. class RelayAdapter(RelayDiscordInteractionMixin, BasePlatformAdapter):
  91. """Generic relay adapter advertising a connector-negotiated capability profile."""
  92. # Connector egress splits against negotiated max_message_length, so the
  93. # gateway-level cap must not pre-truncate relay deliveries.
  94. splits_long_messages = True
  95. def __init__(
  96. self,
  97. config: PlatformConfig,
  98. descriptor: CapabilityDescriptor,
  99. transport: Optional[RelayTransport] = None,
  100. ) -> None:
  101. # Fronts many platforms but presents to the runner as Platform.RELAY.
  102. super().__init__(config, Platform.RELAY)
  103. self._transport = transport
  104. self._apply_descriptor(descriptor)
  105. # Per-chat egress routing caches learned from inbound events (send() only
  106. # receives a chat_id). The connector's egress guard resolves the owning tenant
  107. # from OUTBOUND metadata.scope_id / user_id, so we re-attach what we saw
  108. # inbound (_capture_scope).
  109. self._scope_by_chat: dict[str, str] = {}
  110. self._dm_user_by_chat: dict[str, str] = {}
  111. # chat_id -> chat_type: reproduces native Slack's synthetic DM-thread
  112. # suppression (a raw reply_to becomes a thread_ts connector-side, so a plain
  113. # DM reply would thread under the user).
  114. self._chat_type_by_chat: dict[str, str] = {}
  115. # chat_id -> last triggering Slack message ts (typing/status lane's
  116. # synthetic thread anchor in thread-per-message mode).
  117. self._last_inbound_ts_by_chat: dict[str, str] = {}
  118. # chat_id -> UNDERLYING platform ("discord", ...): one adapter fronts N
  119. # platforms on one WS and a reply must egress through the platform the
  120. # inbound came from. Empty for a single-platform gateway (connector default).
  121. self._platform_by_chat: dict[str, str] = {}
  122. # chat_id -> Hermes profile the connector routed the inbound to (multiplex mode). Echoed
  123. # on every outbound frame's metadata so the connector can stamp the SAME profile on the
  124. # next passthrough_forward for that chat; empty on a single-profile gateway.
  125. self._profile_by_chat: dict[str, str] = {}
  126. # Chats the connector has refused (see the terminal-decline latch).
  127. # chat_id -> (thread_id, initial_name) of the auto-thread the CONNECTOR
  128. # created for our latest send; read by the semantic thread-rename lane.
  129. self._auto_thread_by_chat: dict[str, tuple[str, str]] = {}
  130. # chat_id -> event fired when the entry above lands (wait_for_auto_thread_info).
  131. self._auto_thread_waiters: dict[str, asyncio.Event] = {}
  132. # Bounded FIFO seen-set for inbound replay dedupe (insertion-ordered dict).
  133. self._seen_inbound: dict[str, None] = {}
  134. # Discord chat labels the text lane carries and a forwarded interaction does not:
  135. # (scope, chat) -> (chat_name, chat_topic); the second map is what the store holds.
  136. self._discord_chat_labels: dict[tuple, tuple] = {}
  137. self._discord_labels_recorded: dict[tuple, tuple] = {}
  138. # (platform, chat_id) -> the chat's latest off-reader admission task (inbound_admission).
  139. self._admission_lanes: dict[tuple[str, str], asyncio.Task] = {}
  140. # Live cards: draft_key -> draft_id of the OPEN native stream. Armed by
  141. # send_draft; consumed by send() to convert the turn-final into
  142. # draft(final=true) instead of a duplicate post. Keyed by _draft_key (chat +
  143. # per-turn identity), NOT bare chat: parallel turns in one DM are distinct
  144. # streams (per-chat keying merged three concurrent turns).
  145. self._open_draft_by_chat: dict[str, int] = {}
  146. # draft_key -> draft_id of the most recently SEALED stream (mirror of the
  147. # connector's sealed-key tombstone): post-seal stragglers must neither
  148. # re-arm interception nor re-open a stream.
  149. self._sealed_draft_by_chat: dict[str, int] = {}
  150. # Draft keys whose post-seal swallow has been logged once (bounded FIFO).
  151. self._tombstone_swallow_logged: dict[str, int] = {}
  152. # Strong refs for fire-and-forget lifecycle acks (asyncio holds tasks weakly).
  153. self._lifecycle_ack_tasks: set = set()
  154. # Stream-is-the-message marker read by the stream consumer to keep ONE draft
  155. # stream per turn instead of bumping draft_id at tool boundaries. SLACK-ONLY:
  156. # the base send_draft contract is Telegram-shaped (draft clears, final is a
  157. # separate real send); setting this for any "draft" connector intercepted the
  158. # turn-final into draft(final=true) and no history message was ever posted.
  159. # A future platform with this semantic should advertise it via the descriptor.
  160. self.draft_stream_is_message = str(getattr(descriptor, "platform", "") or "").lower() == "slack"
  161. # Watches the transport for a terminal auth revocation (4401 after a
  162. # successful handshake = operator opted this instance out) and surfaces a
  163. # clean non-retryable "relay disabled" fatal instead of a retry spin.
  164. self._revocation_monitor: Optional[asyncio.Task[None]] = None
  165. # Lazily built client for the connector's /relay/media routes; None when
  166. # dial URL or creds are absent (media lanes degrade to text fallbacks).
  167. self._media_client: Optional[RelayMediaClient] = None
  168. # prompt_id -> pending-prompt state for the interactive `prompt` op; the
  169. # user's pick comes back as a prompt_response naming this id and resolves the
  170. # waiting primitive like native button callbacks. Expire lazily (_pop_prompt).
  171. self._pending_prompts: dict[str, dict[str, Any]] = {}
  172. # Per-process marker prefixed onto every prompt id we mint. WHY: button
  173. # presses ride the passthrough plane, which the connector fans out to EVERY
  174. # live gateway session of the tenant, while _pending_prompts is process-local.
  175. # Without the marker a sibling cannot tell "someone else owns this" from "my
  176. # prompt expired", and the id-shaped text ("/c1") falls through to chat
  177. # dispatch as "Unknown command" — once per sibling (common in a DM).
  178. self._prompt_owner_nonce: str = secrets.token_hex(3)
  179. # Prompt ids this process already resolved, newest last (repeat answers are
  180. # consumed silently instead of treated as stale).
  181. self._resolved_prompts: OrderedDict[str, float] = OrderedDict()
  182. # ── capability surface (from descriptor) ─────────────────────────────
  183. @property
  184. def authorization_is_upstream(self) -> bool:
  185. """The connector enforces authorization (owner-only author-binding before
  186. delivery), so relay users must not be default-denied for lack of a local
  187. ``RELAY_ALLOWED_USERS`` allowlist."""
  188. return True
  189. @property
  190. def message_len_fn(self) -> Callable[[str], int]:
  191. return _LEN_FNS.get(self.descriptor.len_unit, len)
  192. @property
  193. def supports_status_text(self) -> bool: # type: ignore[override]
  194. """Whether the fronted platform renders a TEXT status line: Slack's typing
  195. surface is the assistant status line, so run.py's live-status lane may feed
  196. per-tool phrases; other platforms have textless bubbles and must NOT receive
  197. them. Reflects the PRIMARY identity, like the scalar ``descriptor``."""
  198. return self.descriptor.platform == _SLACK
  199. # ── per-chat capability resolution (multi-platform) ──────────────────
  200. def _negotiated_descriptor(self, platform: Optional[str]) -> Optional[CapabilityDescriptor]:
  201. """The transport's negotiated descriptor for ``platform``, or None (unknown
  202. platform, no transport, or a transport predating ``descriptor_for_platform``).
  203. Never raises — capability lookup must never break a send."""
  204. resolve = getattr(self._transport, "descriptor_for_platform", None) if platform else None
  205. if not callable(resolve):
  206. return None
  207. try:
  208. return resolve(platform)
  209. except Exception:
  210. return None
  211. def _chat_platform(self, chat_id: str) -> Optional[str]:
  212. """The chat's underlying platform as seen inbound, else the primary's."""
  213. return self._platform_by_chat.get(str(chat_id)) or self.descriptor.platform
  214. def _metrics_platform(self, chat_id: str) -> Optional[str]:
  215. """The platform a chat's shared metrics carry: the inbound's, else the primary's only when this
  216. socket fronts one platform (a multi-platform connector's unknown chat stays unlabelled)."""
  217. fronted = {p for p, _ in (getattr(self._transport, "_identities", None) or ())}
  218. return self._platform_by_chat.get(str(chat_id)) or (self.descriptor.platform if len(fronted) <= 1 else None)
  219. def warning_notifications_enabled(self, logical_platform=None, *, chat_id=None, metadata=None) -> bool:
  220. platform = (logical_platform or (metadata or {}).get("_relay_logical_platform")
  221. or self._chat_platform(chat_id))
  222. return super().warning_notifications_enabled(platform)
  223. def _descriptor_for_chat(self, chat_id: str) -> CapabilityDescriptor:
  224. """The descriptor governing a specific chat. Platform caps genuinely differ
  225. (Discord 2000 / Telegram 4096 / Slack 39000), so the primary's scalar cap
  226. either fragments needlessly or over-sends into a platform 400. Falls back to
  227. the scalar when the chat's platform is unknown (never saw inbound)."""
  228. per_platform = self._negotiated_descriptor(self._platform_by_chat.get(str(chat_id)))
  229. return per_platform if per_platform is not None else self.descriptor
  230. def max_message_length_for_chat(self, chat_id: str) -> int:
  231. return self._descriptor_for_chat(chat_id).max_message_length
  232. def message_len_fn_for_chat(self, chat_id: str) -> Callable[[str], int]:
  233. return _LEN_FNS.get(self._descriptor_for_chat(chat_id).len_unit, len)
  234. def supports_draft_streaming(
  235. self,
  236. chat_type: Optional[str] = None,
  237. metadata: Optional[dict[str, Any]] = None,
  238. chat_id: Optional[str] = None,
  239. ) -> bool:
  240. # Needs BOTH the descriptor flag and an explicit "draft" op: supported_ops is
  241. # fail-open for legacy connectors, but "draft" did not exist pre-contract, so
  242. # it must NOT fail open. Resolved per chat when the caller names one (a
  243. # Telegram primary must not starve a Slack chat).
  244. desc = self._descriptor_for_chat(str(chat_id)) if chat_id is not None else self.descriptor
  245. if not (desc.supports_draft_streaming and "draft" in (desc.supported_ops or ())):
  246. return False
  247. # Slack chat.*Stream has no unfurl_links / unfurl_media; like native
  248. # SlackAdapter, refuse streaming when those knobs are set so chat.postMessage
  249. # can carry them.
  250. platform = self._chat_platform(chat_id) if chat_id is not None else desc.platform
  251. return not self._slack_unfurl_hints(platform)
  252. def prefers_fresh_final_streaming(
  253. self,
  254. content: str,
  255. metadata: Optional[dict[str, Any]] = None,
  256. chat_id: Optional[str] = None,
  257. ) -> bool:
  258. """Deliver streamed finals as a FRESH send when Slack unfurl is forced on.
  259. Slack evaluates link previews exactly once, at ``chat.postMessage``; a
  260. ``chat.update`` that INTRODUCES the URL never unfurls. Edit-based streaming
  261. posts its first frame before any URL exists, so a configured ``unfurl_*: true``
  262. can only surface via a fresh final that ``send()`` stamps with the hints. ONLY
  263. when the hints contain an explicit True: false-only hints (fail-closed) ride
  264. the placeholder post fine. Only link-bearing finals qualify — the relay has no
  265. delete op in contract v1, so a linkless fresh final would just be a duplicate.
  266. """
  267. platform = self._platform_by_chat.get(str(chat_id)) if chat_id is not None else None
  268. # The stream consumer's hook passes (content, metadata=...) only.
  269. if platform is None and isinstance(metadata, dict):
  270. platform = metadata.get("platform")
  271. if platform is None:
  272. platform = self.descriptor.platform
  273. hints = self._slack_unfurl_hints(platform)
  274. return bool(hints) and any(v is True for v in hints.values()) and bool(_URL_RE.search(content or ""))
  275. def stream_is_message_for_chat(self, chat_id: str) -> bool:
  276. """Per-chat stream-is-the-message semantic (see ``draft_stream_is_message``).
  277. A Slack primary must not impose seal semantics on a Telegram chat (its
  278. turn-final would become draft(final=true) — no history message), nor a
  279. Telegram primary deny a Slack chat native streaming. Platform-name inference
  280. is deliberate; a descriptor field is the eventual contract."""
  281. return str(self._descriptor_for_chat(str(chat_id)).platform or "").lower() == "slack"
  282. # ── Live cards: native draft streaming + task cards ──────────────────
  283. # Additive relay ops within contract v1, emitted when the negotiated descriptor
  284. # advertises them; the connector owns the platform API mechanics and the
  285. # send+edit fallback. Semantic bridge: the base send_draft contract is
  286. # Telegram-shaped (draft clears, final is a separate send()); Slack native
  287. # streaming makes the stream THE message, so the adapter tracks the open draft
  288. # per turn and converts that turn's final send() into draft(final=true).
  289. def supports_native_task_cards(self) -> bool:
  290. """Explicit advertisement required — same no-fail-open rule as "draft"."""
  291. return "task_card" in (self.descriptor.supported_ops or ())
  292. def native_task_cards_enabled(self) -> bool:
  293. """TurnRunner opt-in probe (gateway/run.py calls THIS name, same contract as
  294. native Slack); without the alias the card lane silently stays text-mode."""
  295. return self.supports_native_task_cards()
  296. @staticmethod
  297. def _draft_key(chat_id: str, metadata: Optional[dict[str, Any]]) -> str:
  298. """Coordination key for one turn's stream. Prefers a PER-TURN identity (the
  299. triggering inbound ``message_id`` / ``reply_to_message_id``) over the thread
  300. anchor: two parallel turns inside ONE thread share thread_ts (turn A's final
  301. sealed turn B's stream), and a flat DM with no anchor degraded to the bare
  302. chat id. Anchor is the fallback for placement-only callers; bare chat last."""
  303. md = metadata or {}
  304. turn_id = md.get("message_id") or md.get("reply_to_message_id")
  305. if turn_id:
  306. return f"{chat_id}:turn:{turn_id}"
  307. anchor = md.get("thread_ts") or md.get("thread_id") or ""
  308. return f"{chat_id}:{anchor}"
  309. # Cap for the draft/seal coordination dicts (per-turn keys); matches the
  310. # connector's tombstone store size.
  311. _DRAFT_STATE_CAP = 512
  312. @classmethod
  313. def _evict_oldest(cls, d: dict[str, Any], cap: Optional[int] = None) -> None:
  314. """FIFO-bound an insertion-ordered dict in place (default cap: draft state)."""
  315. while len(d) > (cls._DRAFT_STATE_CAP if cap is None else cap):
  316. d.pop(next(iter(d)), None)
  317. @staticmethod
  318. def _card_key(reply_to: Optional[str], metadata: Optional[dict[str, Any]]) -> str:
  319. """Per-turn task-card identity — same precedence as ``_draft_key``; one
  320. derivation for send AND stop so the stop always hits the stream the send opened."""
  321. md = metadata or {}
  322. anchor = (
  323. reply_to
  324. or md.get("message_id")
  325. or md.get("reply_to_message_id")
  326. or md.get("thread_ts")
  327. or md.get("thread_id")
  328. or "root"
  329. )
  330. return f"turn:{anchor}"
  331. def _match_open_draft(self, chat_id: str, metadata: Optional[dict[str, Any]]) -> Optional[str]:
  332. """Resolve which open stream (if any) a turn-final send belongs to. Exact key
  333. match first. Callers carrying a per-turn MESSAGE id never fall back — their
  334. identity is authoritative. Callers without one may absorb into the chat's
  335. single open stream; with several open the send stays plain: a duplicate
  336. message is recoverable, sealing someone else's stream is not."""
  337. key = self._draft_key(str(chat_id), metadata)
  338. if key in self._open_draft_by_chat:
  339. return key
  340. md = metadata or {}
  341. if md.get("message_id") or md.get("reply_to_message_id"):
  342. return None
  343. prefix = f"{chat_id}:"
  344. candidates = [k for k in self._open_draft_by_chat if k.startswith(prefix)]
  345. if len(candidates) == 1:
  346. # Absorbing a send into a stream is a significant decision (the
  347. # prompt-ack-seals-own-stream bug); log it so the next mismatch is a grep.
  348. logger.info(
  349. "relay: absorbing identity-less send into the single open "
  350. "stream %s (single-open-stream fallback)",
  351. candidates[0],
  352. )
  353. return candidates[0]
  354. return None
  355. async def _outbound(self, chat_id: str, action: dict[str, Any]) -> dict[str, Any]:
  356. """Send one outbound frame tagged with the chat's underlying platform.
  357. P5(b): the second frame path (the first is ``_gated_op``). Lanes that
  358. return bool/None by contract — typing, delete, thread create/rename —
  359. come through here, and a silent degrade made an AUTHORIZATION refusal
  360. indistinguishable from "op unsupported" in the logs. The return
  361. contract is unchanged; the refusal is recorded.
  362. """
  363. op = str(action.get("op", "?"))
  364. result = await self._transport.send_outbound( # type: ignore[union-attr]
  365. action, platform=self._platform_by_chat.get(str(chat_id))
  366. )
  367. if isinstance(result, dict):
  368. if not result.get("success") and is_egress_decline(result):
  369. log_decline(op, chat_id, result)
  370. return result
  371. async def _gated_op(
  372. self,
  373. chat_id: str,
  374. action: dict[str, Any],
  375. *,
  376. decline_level: Optional[int] = logging.WARNING,
  377. subject: Any = None,
  378. platform: Optional[str] = None,
  379. surface_declines: bool = False,
  380. surface_ambiguous: bool = False,
  381. ) -> Optional[dict[str, Any]]:
  382. """Emit one best-effort, op-gated frame; None when the caller must fall back.
  383. None covers every unavailability: op not advertised (probe the descriptor
  384. instead of parsing a connector error), no transport, transport raised, or a
  385. structured connector decline (logged at ``decline_level``; None = silent);
  386. a lost ack too, unless ``surface_ambiguous`` (a fallback there would re-send).
  387. """
  388. op = action["op"]
  389. if self._transport is None or not self.descriptor.supports_op(op):
  390. return None
  391. try:
  392. result = await self._transport.send_outbound(
  393. action, platform=platform or self._platform_by_chat.get(str(chat_id))
  394. )
  395. except Exception:
  396. logger.debug("relay %s transport failure", op, exc_info=True)
  397. return None
  398. if not result.get("success"):
  399. if surface_ambiguous and result.get("ambiguous"): # frame sent, outcome unknown
  400. return result
  401. # P5(b): an AUTHORIZATION decline is not lane unavailability. This
  402. # helper's `None` means "lane absent — do your fallback", and the
  403. # fallbacks re-address the SAME chat by another route (media -> a
  404. # text notice, prompt -> numbered text). The connector authorized
  405. # that destination and REFUSED it, so degrading launders a security
  406. # decision into "op unsupported" and delivers the content anyway.
  407. # Callers whose fallback would leak pass surface_declines=True and
  408. # turn this into a failed lane; cosmetic ops (typing, card stop)
  409. # keep the old None contract.
  410. if is_egress_decline(result):
  411. # Every lane records an authorization decline — the cosmetic
  412. # ones (typing, delete, thread create/rename, card stop) still
  413. # degrade to None, but a silent degrade made a security refusal
  414. # indistinguishable from "op unsupported" in the logs.
  415. log_decline(op, chat_id if subject is None else subject, result)
  416. if surface_declines:
  417. return result
  418. return None
  419. if decline_level is not None:
  420. logger.log(
  421. decline_level, "relay %s declined for %s: %s",
  422. op, chat_id if subject is None else subject, result.get("error"),
  423. )
  424. return None
  425. return result
  426. def _text_metadata(self, chat_id: str, metadata: Optional[dict[str, Any]]) -> dict[str, Any]:
  427. """Metadata for a text egress frame: format hints + tenant discriminators.
  428. Draft, seal, send and edit are all text lanes — a streamed final can only
  429. render blocks if every frame carries the hint (a hintless seal is the
  430. plain-code-block downgrade)."""
  431. return self._with_scope(chat_id, self._with_format_hints_for_chat(chat_id, metadata))
  432. def _draft_frame(
  433. self, chat_id: str, draft_id: int, content: str, final: bool, metadata: Optional[dict[str, Any]]
  434. ) -> dict[str, Any]:
  435. """One ``draft`` op frame (``final=True`` seals the stream)."""
  436. return {
  437. "op": "draft",
  438. "chat_id": chat_id,
  439. "draft_id": draft_id,
  440. "content": content,
  441. "final": final,
  442. "metadata": self._text_metadata(chat_id, dict(metadata or {})),
  443. }
  444. async def send_draft(
  445. self, chat_id: str, draft_id: int, content: str, metadata: Optional[dict[str, Any]] = None,
  446. ) -> SendResult:
  447. if not self.supports_draft_streaming(chat_id=str(chat_id)):
  448. raise NotImplementedError("connector does not advertise the 'draft' relay op")
  449. if self._transport is None:
  450. return SendResult(success=False, error="no transport")
  451. # Arm optimistically BEFORE the transport call (a lossy ack often means
  452. # delivered), but NEVER for a draft_id already sealed on this key: a straggler
  453. # after the seal re-armed interception with no live stream, and the next
  454. # unrelated send was wrongly converted into a seal.
  455. chat_key = self._draft_key(str(chat_id), metadata)
  456. if self._sealed_draft_by_chat.get(chat_key) == draft_id:
  457. # Post-seal straggler: content is already in the sealed message; report
  458. # success, send nothing. Log the FIRST swallow per key — one straggler is
  459. # the normal race, but a burst means something sealed a live stream
  460. # mid-flight (silence here cost a forensic hunt).
  461. if chat_key not in self._tombstone_swallow_logged:
  462. self._tombstone_swallow_logged[chat_key] = draft_id
  463. self._evict_oldest(self._tombstone_swallow_logged)
  464. logger.warning(
  465. "relay: draft frame for %s swallowed by post-seal "
  466. "tombstone (draft_id=%s) — expected for a straggler; "
  467. "a live stream freezing NOW means something sealed it "
  468. "mid-flight",
  469. chat_key,
  470. draft_id,
  471. )
  472. return SendResult(success=True)
  473. # Arm seal-interception ONLY for stream-is-the-message chats: on a
  474. # Telegram-shaped connector the final MUST go out as a real send.
  475. if self.stream_is_message_for_chat(str(chat_id)):
  476. self._open_draft_by_chat[chat_key] = draft_id
  477. self._evict_oldest(self._open_draft_by_chat)
  478. try:
  479. result = await self._outbound(chat_id, self._draft_frame(chat_id, draft_id, content, False, metadata))
  480. except Exception as e:
  481. # Ambiguous (stale socket, mid-write drop): may have been delivered;
  482. # keep interception armed.
  483. return SendResult(success=False, error=f"draft transport error: {e}")
  484. if result.get("success"):
  485. return SendResult(success=True)
  486. if result.get("ambiguous"):
  487. # Ack lost (transport timeout, returned rather than raised): same
  488. # contract as the except branch — keep interception armed.
  489. #
  490. # RAW BODY PRESERVED. Dropping it made `declined_send` fall through
  491. # to the error-text branch, and an ambiguous result whose text
  492. # happens to carry the decline marker ("... egress declined: ack
  493. # lost") then read as a DEFINITE refusal and terminated the run.
  494. # Ambiguous means the frame may well have been delivered, so it is
  495. # a transport outcome, never an authorization one.
  496. return SendResult(
  497. success=False,
  498. error=str(result.get("error") or "draft ack lost"),
  499. raw_response=result,
  500. )
  501. # DEFINITE connector rejection: disarm. The stream consumer falls back to
  502. # edit-based streaming and its turn-final must go out as a REAL send, not a
  503. # seal on a stream the connector just declared unusable.
  504. if self._open_draft_by_chat.get(chat_key) == draft_id:
  505. self._open_draft_by_chat.pop(chat_key, None)
  506. # P5(b): carry the structured body. The stream consumer reads a bare
  507. # draft failure as "draft transport unusable", disables drafts, and
  508. # falls through to a plain send — a second op against the chat the
  509. # connector just refused. Verified end to end with the real
  510. # GatewayStreamConsumer: ops were ['draft', 'send'].
  511. if is_egress_decline(result):
  512. log_decline("draft", chat_id, result)
  513. return SendResult(
  514. success=False,
  515. error=str(result.get("error") or decline_error(result) or "draft failed"),
  516. raw_response=result,
  517. )
  518. async def _seal_open_draft(
  519. self,
  520. chat_id: str,
  521. content: str,
  522. metadata: Optional[dict[str, Any]],
  523. *,
  524. draft_key: Optional[str] = None,
  525. ) -> SendResult:
  526. """Convert the turn-final send into the sealing draft frame."""
  527. if draft_key is None:
  528. draft_key = self._draft_key(str(chat_id), metadata)
  529. draft_id = self._open_draft_by_chat.pop(draft_key)
  530. # Tombstone BEFORE the transport call: whatever the ack says, this draft_id
  531. # must never be re-armed by a straggler frame.
  532. self._sealed_draft_by_chat[draft_key] = draft_id
  533. self._evict_oldest(self._sealed_draft_by_chat)
  534. if self._transport is None:
  535. return SendResult(success=False, error="no transport")
  536. seal_frame = self._draft_frame(chat_id, draft_id, content, True, metadata)
  537. _seal_platform = self._platform_by_chat.get(str(chat_id))
  538. _transport = self._transport # narrowed by the None-guard above
  539. async def _attempt() -> Optional[dict[str, Any]]:
  540. """One seal attempt; None means ambiguous (exception or lost ack)."""
  541. try:
  542. r = await _transport.send_outbound(seal_frame, platform=_seal_platform)
  543. except Exception as e:
  544. logger.warning("relay seal transport error (ambiguous): %s", e)
  545. return None
  546. if r.get("ambiguous"):
  547. logger.warning("relay seal ack lost (ambiguous): %s", r.get("error"))
  548. return None
  549. return r
  550. # Ambiguous outcomes retry the SAME idempotent frame once: the connector's
  551. # sealed-key tombstone returns the original stream ts for a repeated final
  552. # and never opens a second stream. Two consecutive ack losses on one socket
  553. # almost always mean the transport is down. Cancellation safety: the open
  554. # entry was popped and the tombstone written BEFORE the await; restore both
  555. # before re-raising so the later abandon pass can still seal the stream.
  556. try:
  557. result = await _attempt()
  558. if result is None:
  559. result = await _attempt()
  560. except asyncio.CancelledError:
  561. self._open_draft_by_chat[draft_key] = draft_id
  562. if self._sealed_draft_by_chat.get(draft_key) == draft_id:
  563. self._sealed_draft_by_chat.pop(draft_key, None)
  564. raise
  565. if result is None:
  566. # Same ambiguity contract as send_draft: the retry's ack was lost,
  567. # so the seal may have been applied. Marked explicitly rather than
  568. # left to text inference.
  569. return SendResult(
  570. success=False,
  571. error="draft seal ambiguous after retry (transport ack lost)",
  572. raw_response={"success": False, "ambiguous": True},
  573. )
  574. if result.get("success"):
  575. # The connector returns the stream's ts as the message identity.
  576. return SendResult(success=True, message_id=str(result.get("message_id") or "") or None)
  577. # P5(b): carry the structured body. Without it the caller cannot tell a
  578. # lane failure (fall through to a plain send, correct) from an
  579. # AUTHORIZATION decline (a plain send re-delivers the very content the
  580. # connector refused, to the same chat).
  581. if is_egress_decline(result):
  582. log_decline("draft_seal", chat_id, result)
  583. return SendResult(
  584. success=False,
  585. error=str(result.get("error") or decline_error(result) or "draft seal failed"),
  586. raw_response=result,
  587. )
  588. async def _absorb_into_open_draft(
  589. self, chat_id: str, content: str, metadata: dict[str, Any], interim: bool
  590. ) -> Optional[SendResult]:
  591. """Seal an open native stream with this turn-final; None = do a plain send.
  592. An open stream absorbs the turn-final whichever egress door it arrives
  593. through (send / send_for_platform) — otherwise the stream is left frozen
  594. mid-word AND the final posts as a duplicate. A failed seal must NOT swallow
  595. the final: the consumer already disabled the draft transport, so fall through
  596. to a plain send (the orphaned stream is sealed connector-side). Interim sends
  597. (commentary, tail flush, lifecycle acks) never seal.
  598. """
  599. if interim:
  600. return None
  601. key = self._match_open_draft(str(chat_id), metadata)
  602. if key is None:
  603. return None
  604. seal = await self._seal_open_draft(chat_id, content, metadata, draft_key=key)
  605. if seal.success:
  606. return seal
  607. # An AUTHORIZATION decline is not a lane failure. Falling through here
  608. # re-sends the sealed content as a plain `send` into the destination the
  609. # connector just refused — review demonstrated the leak end to end
  610. # (ops: draft(partial) -> send(SECRET)). Surface the refusal instead.
  611. if is_egress_decline(getattr(seal, "raw_response", None)):
  612. logger.warning(
  613. "relay draft seal DECLINED for %s — not falling back to a plain "
  614. "send (the destination is not approved for this connection)",
  615. chat_id,
  616. )
  617. return seal
  618. logger.warning("relay seal failed (%s); delivering turn-final as plain send", seal.error)
  619. return None
  620. async def _card_frame(
  621. self, chat_id: str, op: str, reply_to: Optional[str], metadata: dict[str, Any], **fields: Any
  622. ) -> SendResult | dict[str, Any]:
  623. """Emit one task-card op: the connector result dict, or a failed SendResult
  624. when the lane is unavailable / the transport raised.
  625. Card frames are advisory and run inside the progress loop / turn-cleanup
  626. path: an escaping exception there skipped final delivery, so transport
  627. errors degrade to the TurnRunner's text fallback instead of raising.
  628. """
  629. if not self.supports_native_task_cards():
  630. return SendResult(success=False, error="connector does not advertise task_card")
  631. if self._transport is None:
  632. return SendResult(success=False, error="no transport")
  633. frame = {
  634. "op": op,
  635. "chat_id": chat_id,
  636. "card_id": self._card_key(reply_to, metadata),
  637. **fields,
  638. "metadata": self._with_scope(chat_id, metadata),
  639. }
  640. try:
  641. return await self._outbound(chat_id, frame)
  642. except Exception as e:
  643. return SendResult(success=False, error=f"{op} transport error: {e}")
  644. @staticmethod
  645. def _task_card_metadata(
  646. reply_to: Optional[str], metadata: Optional[dict[str, Any]],
  647. ) -> dict[str, Any]:
  648. merged_meta = dict(metadata or {})
  649. if reply_to and "thread_ts" not in merged_meta:
  650. # Slack card streams are thread replies anchored on the trigger.
  651. merged_meta["thread_ts"] = str(reply_to)
  652. return merged_meta
  653. def native_task_card_destination_supported(
  654. self, chat_id: str, *, reply_to: Optional[str] = None,
  655. metadata: Optional[dict[str, Any]] = None,
  656. ) -> bool:
  657. """Check the actual card-frame placement, not its per-turn card identity."""
  658. if self._chat_platform(chat_id) != _SLACK:
  659. return True
  660. md = self._task_card_metadata(reply_to, metadata)
  661. # Connector threadTs(): thread_id ?? thread_ts, and only strings thread.
  662. thread = md.get("thread_id")
  663. if thread is None:
  664. thread = md.get("thread_ts")
  665. return isinstance(thread, str)
  666. async def send_native_task_card_progress(
  667. self,
  668. chat_id: str,
  669. tasks: list,
  670. *,
  671. title: str = "Hermes is working",
  672. reply_to: Optional[str] = None,
  673. metadata: Optional[dict[str, Any]] = None,
  674. fallback_text: Optional[str] = None,
  675. ) -> SendResult:
  676. """Relay leg of the task-card lane: emit one card frame.
  677. SIGNATURE CONTRACT: the TurnRunner calls this with the NATIVE Slack
  678. adapter's keyword contract, not a card_id. ``fallback_text``/``title``
  679. are accepted for parity but not forwarded (the connector's plan-mode
  680. stream renders task chunks; field limits are enforced connector-side).
  681. See #85476.
  682. """
  683. merged_meta = self._task_card_metadata(reply_to, metadata)
  684. result = await self._card_frame(
  685. chat_id, "task_card", reply_to, merged_meta, chunks=[dict(task) for task in tasks]
  686. )
  687. if isinstance(result, SendResult):
  688. return result
  689. if result.get("success"):
  690. return SendResult(success=True)
  691. # P5(b): carry the structured body. The TurnRunner reads a bare failure
  692. # as "card lane unavailable" and sends fallback TEXT to the same chat —
  693. # the same decline-laundering fixed for media and prompt, in a sibling
  694. # content lane.
  695. if is_egress_decline(result):
  696. log_decline("task_card", chat_id, result)
  697. return SendResult(
  698. success=False,
  699. error=str(result.get("error") or decline_error(result) or "task_card failed"),
  700. raw_response=result,
  701. )
  702. async def stop_native_task_card_progress(
  703. self,
  704. chat_id: str,
  705. *,
  706. reply_to: Optional[str] = None,
  707. metadata: Optional[dict[str, Any]] = None,
  708. ) -> SendResult:
  709. """Seal the card stream at turn end (idempotent connector-side); same key derivation as send."""
  710. result = await self._card_frame(chat_id, "task_card_stop", reply_to, dict(metadata or {}))
  711. if isinstance(result, SendResult):
  712. return result
  713. # P5(b): carry the connector's reason. Dropping `error` reported a
  714. # refusal as a bare failure, which reads as "the card lane is broken"
  715. # rather than "this destination was refused".
  716. return SendResult(
  717. success=bool(result.get("success")),
  718. error=result.get("error"),
  719. raw_response=result,
  720. )
  721. async def abandon_open_draft(
  722. self, chat_id: str, content: str, metadata: Optional[dict[str, Any]] = None,
  723. ) -> SendResult:
  724. """Seal an orphaned stream when its turn dies (/stop, /new, supersede), in
  725. place with ``content`` (the text already on screen) so the seal adds and
  726. claims nothing; otherwise the live indicator stays forever and the NEXT turn
  727. could inherit the armed interception state. Failure is reported, never raised."""
  728. draft_key = self._match_open_draft(str(chat_id), metadata)
  729. if draft_key is None:
  730. return SendResult(success=True) # nothing armed — no-op
  731. try:
  732. return await self._seal_open_draft(chat_id, content, metadata, draft_key=draft_key)
  733. except Exception as e:
  734. return SendResult(success=False, error=f"abandon seal transport error: {e}")
  735. # ── abstract methods (delegated to the transport) ────────────────────
  736. async def connect(self, *, is_reconnect: bool = False) -> bool:
  737. # ``is_reconnect`` is part of the BasePlatformAdapter.connect contract (the
  738. # reconnect watcher passes it; refusing the kwarg would break recovery).
  739. # Relay IGNORES it: messages buffered during a gap live in the CONNECTOR's
  740. # durable buffer and replay on re-handshake; routine WS drops are handled by
  741. # the transport's own reconnect supervisor.
  742. if self._transport is None:
  743. # ``is_reconnect`` is part of the BasePlatformAdapter.connect contract: the gateway's reconnect
  744. # watcher (gateway/run.py) re-establishes a platform after a fatal adapter error by building a
  745. # fresh adapter and calling ``connect(is_reconnect=True)``. Relay MUST accept the kwarg or that
  746. # recovery path raises TypeError and the relay platform can never come back through the watcher.
  747. # The flag exists so adapters with a server-side update queue (e.g. Telegram's Bot API) preserve
  748. # that queue across an outage instead of dropping it (#46621). Routine WS drops are handled
  749. # entirely by the transport's own reconnect supervisor (WebSocketRelayTransport,
  750. # reconnect=True); a watcher-driven reconnect builds a fresh transport from scratch (the
  751. # fatal-error handler disconnect()s the old adapter first, cancelling its supervisor), so there
  752. # is nothing at the adapter layer to preserve.
  753. raise RuntimeError("RelayAdapter has no transport configured")
  754. self._transport.set_inbound_handler(self._on_inbound)
  755. # Interrupts and passthrough-plane forwards (Discord interactions, Twilio, …)
  756. # ride the SAME outbound WS — no inbound HTTP receiver, no public port.
  757. for setter_name, handler in (
  758. ("set_interrupt_inbound_handler", self.on_interrupt),
  759. ("set_passthrough_handler", self._on_passthrough),
  760. ):
  761. setter = getattr(self._transport, setter_name, None)
  762. if callable(setter):
  763. setter(handler)
  764. if not await self._transport.connect():
  765. return False
  766. # Adopt the connector-advertised descriptor in place of the placeholder.
  767. try:
  768. descriptor = await self._transport.handshake()
  769. except Exception as exc:
  770. logger.warning("relay handshake failed: %s", exc)
  771. return False
  772. self._apply_descriptor(descriptor)
  773. # Only the production WebSocket transport exposes `auth_revoked`.
  774. if hasattr(self._transport, "auth_revoked"):
  775. self._start_revocation_monitor()
  776. return True
  777. def _start_revocation_monitor(self) -> None:
  778. """Spawn (once) the task turning a transport auth-revocation into a clean
  779. non-retryable 'relay disabled' fatal. Idempotent."""
  780. if self._revocation_monitor is not None and not self._revocation_monitor.done():
  781. return
  782. try:
  783. self._revocation_monitor = asyncio.create_task(
  784. self._watch_for_revocation(), name="relay-revocation-monitor"
  785. )
  786. except RuntimeError:
  787. # No running loop (a unit test calling connect() via a stub).
  788. self._revocation_monitor = None
  789. async def _watch_for_revocation(self, poll_interval_s: float = 1.0) -> None:
  790. """Poll for a terminal 4401 revocation (opt-out), then surface a non-retryable
  791. `relay_disabled` fatal so the adapter is cleanly removed rather than queued
  792. for reconnection (the credential is dead until the instance is recreated)."""
  793. transport = self._transport
  794. if transport is None:
  795. return
  796. while not getattr(transport, "auth_revoked", False):
  797. await asyncio.sleep(poll_interval_s)
  798. logger.warning("relay credential revoked (opt-out) — marking the relay adapter disabled")
  799. self._set_fatal_error(
  800. "relay_disabled", "Relay disabled (opted out — recreate the instance to re-enable)",
  801. retryable=False,
  802. )
  803. try:
  804. await self._notify_fatal_error()
  805. except Exception:
  806. logger.debug("relay revocation fatal-error notify failed", exc_info=True)
  807. def _apply_descriptor(self, descriptor: CapabilityDescriptor) -> None:
  808. """Adopt a (re)negotiated descriptor into the live capability surface."""
  809. self.descriptor = descriptor
  810. self.MAX_MESSAGE_LENGTH = descriptor.max_message_length
  811. self.supports_code_blocks = descriptor.markdown_dialect not in ("", "plain")
  812. # Cron in_channel continuable surface (D6 gate in cron/scheduler.py);
  813. # class default is False, so only an explicit descriptor bit turns it on.
  814. self.supports_inchannel_continuable = bool(getattr(descriptor, "supports_inchannel_continuable", False))
  815. async def _on_inbound(self, event) -> Optional[asyncio.Task]:
  816. """Bridge a connector-delivered MessageEvent into the normal adapter path; a task when its
  817. admission runs off the reader (``admit_relay_delivery``) and the transport ACKs on its end."""
  818. # Inbound replay dedupe: the relay leg is at-least-once — on WS re-handshake
  819. # the connector replays its durable buffer, and a long turn straddling a
  820. # quiet socket drop got re-run (final answer 2-5x). Platform message identity
  821. # is stable across replays.
  822. runner = getattr(self._message_handler, '__self__', None)
  823. native = getattr(runner, 'session_authority', None) is not None and not event.get_command()
  824. dedupe_key = None if native else self._inbound_dedupe_key(event)
  825. if dedupe_key is not None:
  826. if dedupe_key in self._seen_inbound:
  827. logger.info("relay inbound dropped as replay (dedupe key=%s)", dedupe_key)
  828. return
  829. self._seen_inbound[dedupe_key] = None
  830. self._evict_oldest(self._seen_inbound, self._SEEN_INBOUND_MAX)
  831. try:
  832. self._capture_ingress_scope(event)
  833. await self._remember_discord_labels(event.source)
  834. self._stamp_slack_session_thread(event)
  835. # A structured prompt answer resolves its waiting primitive and is CONSUMED —
  836. # never also dispatched as chat.
  837. if await self._consume_prompt_response(event):
  838. return
  839. await self._localize_inbound_media(event)
  840. except asyncio.CancelledError:
  841. # Teardown cancels the reader mid-frame, before admission and before the ACK, so the
  842. # connector replays this frame; the replay must be admitted, not dropped as seen.
  843. if dedupe_key is not None:
  844. self._seen_inbound.pop(dedupe_key, None)
  845. raise
  846. if native:
  847. from datetime import datetime
  848. from gateway.relay.inbound_admission import admit_relay_delivery
  849. # The connector does not transmit a provider timestamp. Local arrival
  850. # time must not change the fingerprint of a retried provider identity.
  851. event.timestamp = datetime.fromtimestamp(0, UTC)
  852. # Never wait for inference or outbound ACKs (those need this same WS reader).
  853. return await admit_relay_delivery(self, runner, event)
  854. await self.handle_message(event)
  855. return None
  856. _SEEN_INBOUND_MAX = 512
  857. def _inbound_dedupe_key(self, event) -> Optional[str]:
  858. """Stable replay identity: (platform, chat, platform message id). The platform
  859. joins the key because one relay socket can front several platforms whose
  860. numeric ids may collide. None when the event carries no platform message id —
  861. those never dedupe (fail-open: dropping a real message beats rerunning one)."""
  862. source = getattr(event, "source", None)
  863. message_id = getattr(event, "message_id", None)
  864. chat_id = getattr(source, "chat_id", None)
  865. if not message_id or not chat_id:
  866. return None
  867. # Enum value when present, plain string otherwise: both spellings of one
  868. # platform must produce ONE key.
  869. raw_platform = getattr(source, "platform", None)
  870. platform = getattr(raw_platform, "value", raw_platform) or ""
  871. return f"{platform}:{chat_id}:{message_id}"
  872. def _relay_platform_extra(self, platform: str) -> dict[str, Any]:
  873. """``platforms.relay.extra.<platform>.*`` — relay-namespaced mirror of a native
  874. platform's knobs (``platforms.<platform>`` keeps meaning native settings).
  875. Legacy fallback: flat keys on the relay extra when no ``<platform>`` object exists."""
  876. extra = getattr(self.config, "extra", None) or {}
  877. sub = extra.get(platform)
  878. return sub if isinstance(sub, dict) else extra
  879. def _relay_slack_extra(self) -> dict[str, Any]:
  880. return self._relay_platform_extra("slack")
  881. @staticmethod
  882. def _coerce_flag(raw: Any, default: bool) -> bool:
  883. """Coerce an operator-supplied boolean exactly as native Slack does: a
  884. YAML-quoted ``"false"`` must turn the flag OFF (bare ``bool()`` would read
  885. the non-empty string as True and silently ignore the switch)."""
  886. if raw is None:
  887. return default
  888. return raw if isinstance(raw, bool) else str(raw).strip().lower() in _TRUTHY
  889. def _slack_flag(self, knob: str, default: bool) -> bool:
  890. """A coerced boolean knob from the relay Slack extra; ``default`` on any config-shape error."""
  891. try:
  892. return self._coerce_flag(self._relay_slack_extra().get(knob), default)
  893. except Exception:
  894. return default
  895. def _effective_reply_in_thread(self) -> bool:
  896. """Resolve the thread-per-message vs flat-DM mode for fronted Slack."""
  897. return self._slack_flag("reply_in_thread", True)
  898. def _dm_top_level_threads_as_sessions(self) -> bool:
  899. """Native-parity escape hatch: per-message DM sessions on/off. Default True:
  900. in thread-per-message mode each top-level DM message keys its own session.
  901. False keeps threaded PLACEMENT but ONE rolling DM session (legacy steer/queue
  902. posture), decoupled from reply_in_thread."""
  903. return self._slack_flag("dm_top_level_threads_as_sessions", True)
  904. def _slack_unfurl_hints(self, platform: Optional[str]) -> Optional[dict[str, bool]]:
  905. """Slack-only outbound link-preview knobs (``unfurl_links``/``unfurl_media``)
  906. from the relay namespace. Only explicitly configured booleans are returned
  907. (omitted keys preserve Slack's default); YAML strings are coerced, junk
  908. dropped. Non-Slack platforms return None so their metadata is never polluted."""
  909. if str(platform or "").lower() != _SLACK:
  910. return None
  911. extra = self._relay_slack_extra()
  912. hints: dict[str, bool] = {}
  913. for knob in ("unfurl_links", "unfurl_media"):
  914. val = extra.get(knob)
  915. if isinstance(val, bool):
  916. hints[knob] = val
  917. elif isinstance(val, str) and val.strip().lower() in (_TRUTHY | _FALSY):
  918. hints[knob] = val.strip().lower() in _TRUTHY
  919. return hints or None
  920. def _stamp_slack_unfurl(self, platform: Optional[str], metadata: dict[str, Any]) -> None:
  921. unfurl = self._slack_unfurl_hints(platform)
  922. if unfurl:
  923. metadata.update(unfurl)
  924. def _stamp_slack_session_thread(self, event) -> None:
  925. """Native session-keying parity for fronted Slack DMs.
  926. Native Slack stamps ``thread_ts = event.thread_ts or ts``, so each TOP-LEVEL
  927. message keys a FRESH session (parallel turns). The connector normalizes
  928. top-level messages with thread_id=null, so without this every top-level DM
  929. collapsed into ONE session and message 2 pre-empted message 1. Only in
  930. thread-per-message mode (flat mode keeps the shared rolling session on
  931. purpose); never overwrites a real thread_id.
  932. """
  933. try:
  934. src = getattr(event, "source", None)
  935. if not src:
  936. return
  937. platform = getattr(src, "platform", None)
  938. if getattr(platform, "value", platform) != _SLACK:
  939. return
  940. if getattr(src, "thread_id", None):
  941. return # real thread — its session key is already correct
  942. message_id, _chat = _event_ids(event)
  943. if not message_id or not self._effective_reply_in_thread():
  944. return
  945. if not self._dm_top_level_threads_as_sessions():
  946. return # opt-out: threaded replies, one rolling session
  947. src.thread_id = str(message_id)
  948. except Exception:
  949. logger.debug("slack session-thread stamp failed", exc_info=True)
  950. async def _localize_inbound_media(self, event) -> None:
  951. """Download connector re-hosted attachments to local temp paths — every NATIVE
  952. adapter presents inbound media as LOCAL FILE PATHS (vision/file tools consume
  953. paths). Best-effort per entry: a failed download drops that entry, never the
  954. message; with no client only re-host URLs are dropped (they'd 401 downstream)."""
  955. try:
  956. urls = list(getattr(event, "media_urls", None) or [])
  957. if not urls:
  958. return
  959. # media_types / media_filenames are INDEXED IN PARALLEL with media_urls downstream:
  960. # carry (url, mime, name) TRIPLES or survivors inherit a neighbour's type or name.
  961. types = list(getattr(event, "media_types", None) or []) + [""] * len(urls)
  962. names = list(getattr(event, "media_filenames", None) or []) + [""] * len(urls)
  963. client = self._get_media_client()
  964. localized: list[tuple[str, str, str]] = []
  965. for url, mime, name in zip(urls, types, names):
  966. if not isinstance(url, str) or not url:
  967. continue
  968. if client is None:
  969. if "/relay/media/" not in url:
  970. localized.append((url, mime, name))
  971. continue
  972. # The path is a random temp name; the original name rides beside it.
  973. got = await client.download_with_name(url, suggested_name=name or None)
  974. if got:
  975. localized.append((got[0], mime, got[1]))
  976. elif "/relay/media/" not in url:
  977. # A public URL still has value as a URL; a dead re-host does not.
  978. localized.append((url, mime, name))
  979. event.media_urls, event.media_types, event.media_filenames = (
  980. [entry[i] for entry in localized] for i in range(3))
  981. except Exception:
  982. logger.debug("relay inbound media localization failed", exc_info=True)
  983. def prime_routing_cache(self, event) -> None:
  984. """Warm the per-chat egress routing caches from a SYNTHETIC event: a completion
  985. turn injected right after a restart (durable async-delegation replay) reaches
  986. handle_message with the caches COLD, so its replies egress without
  987. scope_id/user_id and the connector's fail-closed tenant guard declines them."""
  988. if event is None or getattr(event, "source", None) is None:
  989. return
  990. self._capture_scope(event)
  991. def _capture_scope(self, event) -> None:
  992. """Remember a chat's egress discriminators from an inbound event. Never raises.
  993. scope_id: scoped (guild/channel) message → routing-table resolution. user_id:
  994. authentic author id, captured for EVERY message — sole discriminator for a DM
  995. AND the author-first fallback for a scoped reply whose guild has no route row
  996. (managed agents join guilds dynamically). Without a resolvable discriminator
  997. the connector declines egress as 'target not routed to an onboarded tenant'.
  998. """
  999. try:
  1000. src = getattr(event, "source", None)
  1001. chat = getattr(src, "chat_id", None) if src else None
  1002. if not chat:
  1003. return
  1004. chat = str(chat)
  1005. # Underlying platform's string VALUE, skipping the generic RELAY
  1006. # fallback (the connector's session default handles egress then).
  1007. platform = getattr(src, "platform", None)
  1008. platform_value = getattr(platform, "value", platform)
  1009. if platform_value and platform_value != "relay":
  1010. self._platform_by_chat[chat] = str(platform_value)
  1011. for attr, cache in (
  1012. ("user_id", self._dm_user_by_chat), ("scope_id", self._scope_by_chat),
  1013. ("chat_type", self._chat_type_by_chat),
  1014. ("profile", self.__dict__.setdefault("_profile_by_chat", {})),
  1015. ):
  1016. value = getattr(src, attr, None)
  1017. if value:
  1018. cache[chat] = str(value)
  1019. # Latest message ts: the status anchor for typing frames that carry no turn's own anchor.
  1020. message_id, _chat = _event_ids(event)
  1021. if message_id:
  1022. self._last_inbound_ts_by_chat[chat] = str(message_id)
  1023. except Exception:
  1024. pass
  1025. def _with_scope(self, chat_id: str, metadata: Optional[dict[str, Any]]) -> dict[str, Any]:
  1026. """Outbound metadata carrying the tenant discriminators (see _capture_scope).
  1027. Both are attached when known and not already set; the connector tries scope_id
  1028. first and only falls back to user_id on a route miss, so carrying both never
  1029. overrides routing-table resolution."""
  1030. meta: dict[str, Any] = dict(metadata or {})
  1031. # ``getattr``: relay tests build bare adapters via ``__new__`` without ``__init__``.
  1032. for key, cache in (
  1033. ("scope_id", self._scope_by_chat), ("user_id", self._dm_user_by_chat),
  1034. ("profile", getattr(self, "_profile_by_chat", {})),
  1035. ):
  1036. if not meta.get(key):
  1037. value = cache.get(str(chat_id))
  1038. if value:
  1039. meta[key] = value
  1040. return meta
  1041. def fronts_platform(self, platform: Any) -> bool:
  1042. """Whether the authenticated relay transport advertises ``platform`` — a
  1043. restart-safe ownership signal from the identity set sent at handshake, not
  1044. from an inbound chat cache."""
  1045. platform_value = getattr(platform, "value", platform)
  1046. ids = getattr(self._transport, "_identities", None) or ()
  1047. return bool(platform_value) and any(p == str(platform_value) for p, _ in ids)
  1048. def supports_inchannel_continuable_for_platform(self, platform: Any) -> bool:
  1049. """Whether ONE fronted platform can host the flat continuable cron surface (D6
  1050. gate). The scalar bit is the PRIMARY's only, so resolve the platform's own
  1051. negotiated descriptor; fall back to the scalar when unavailable."""
  1052. per_platform = self._negotiated_descriptor(str(getattr(platform, "value", platform) or ""))
  1053. if per_platform is not None:
  1054. return bool(getattr(per_platform, "supports_inchannel_continuable", False))
  1055. return bool(self.supports_inchannel_continuable)
  1056. async def on_interrupt(self, session_key: str, chat_id: str) -> None:
  1057. """Bridge a connector-delivered /stop into the per-session interrupt path."""
  1058. await self.interrupt_session_activity(session_key, chat_id)
  1059. async def disconnect(self) -> None:
  1060. # The runner wraps this call in wait_for(adapter disconnect budget). Monitor
  1061. # teardown and go_idle eat into the transport's drain time, so measure from
  1062. # the top and thread the REMAINDER down — otherwise teardown is cancelled
  1063. # mid-drain and the transport's fail-pending loop is skipped (callers then
  1064. # block on _OUTBOUND_TIMEOUT_S).
  1065. from gateway.relay.ws_transport import _env_disconnect_budget_s
  1066. _started = time.monotonic()
  1067. _budget = _env_disconnect_budget_s()
  1068. # Stop the revocation monitor first so it can't fire a spurious fatal
  1069. # during/after a deliberate teardown.
  1070. if self._revocation_monitor is not None:
  1071. self._revocation_monitor.cancel()
  1072. try:
  1073. await asyncio.wait_for(
  1074. self._revocation_monitor, timeout=_RELAY_REVOCATION_MONITOR_TEARDOWN_TIMEOUT_S
  1075. )
  1076. except (TimeoutError, asyncio.CancelledError, Exception):
  1077. pass
  1078. self._revocation_monitor = None
  1079. if self._transport is not None:
  1080. # Ask the connector to flip this instance to buffered-only BEFORE tearing
  1081. # down the socket, so inbound arriving while asleep buffers durably and
  1082. # replays on reconnect. Best-effort: a transport without go_idle (the
  1083. # stub) or a failed ack must not block shutdown. transport.disconnect()
  1084. # runs in finally so an outer cancellation during go_idle still closes the
  1085. # socket/supervisor; shield() keeps the teardown await itself from being
  1086. # cancelled mid-flight.
  1087. try:
  1088. go_idle = getattr(self._transport, "go_idle", None)
  1089. if callable(go_idle):
  1090. try:
  1091. result: Any = go_idle(timeout_s=_RELAY_GO_IDLE_ON_DISCONNECT_TIMEOUT_S)
  1092. if asyncio.iscoroutine(result):
  1093. await result
  1094. except Exception:
  1095. logger.debug("relay going_idle failed during drain", exc_info=True)
  1096. finally:
  1097. try:
  1098. _remaining = max(0.0, _budget - (time.monotonic() - _started))
  1099. try:
  1100. _td = self._transport.disconnect(budget_s=_remaining) # type: ignore[call-arg]
  1101. except TypeError:
  1102. # Transports without the budget_s keyword (stubs).
  1103. _td = self._transport.disconnect()
  1104. await asyncio.shield(_td)
  1105. except Exception:
  1106. logger.debug("relay transport disconnect failed during drain", exc_info=True)
  1107. async def go_dormant(self) -> bool:
  1108. """Quiesce the relay for a scale-to-zero suspend. Unlike ``disconnect()`` this
  1109. keeps the reconnect path armed so the gateway re-dials and drains its backlog
  1110. on wake. A transport without ``go_dormant`` (the stub) is a no-op returning
  1111. False. Deliberately does NOT stop the revocation monitor — dormancy is not a
  1112. teardown."""
  1113. go_dormant = getattr(self._transport, "go_dormant", None)
  1114. if not callable(go_dormant):
  1115. return False
  1116. try:
  1117. result: Any = go_dormant()
  1118. return bool(await result) if asyncio.iscoroutine(result) else bool(result)
  1119. except Exception:
  1120. logger.debug("relay go_dormant failed", exc_info=True)
  1121. return False
  1122. def hold_redial(self) -> bool:
  1123. """Park the transport's reconnect supervisor. False if it did not take.
  1124. The caller suspends on the strength of this, so a swallowed failure here
  1125. would report protection that was never installed.
  1126. """
  1127. return self._toggle_transport_redial("hold_redial")
  1128. def release_redial(self) -> bool:
  1129. """Undo hold_redial() when the suspend did not land."""
  1130. return self._toggle_transport_redial("release_redial")
  1131. def _toggle_transport_redial(self, method_name: str) -> bool:
  1132. # Still never raises into the idle path, but a stub transport or a
  1133. # throwing toggle now reports False instead of passing for success.
  1134. method = getattr(self._transport, method_name, None)
  1135. if not callable(method):
  1136. return False
  1137. try:
  1138. method()
  1139. except Exception:
  1140. logger.debug("relay %s failed", method_name, exc_info=True)
  1141. return False
  1142. return True
  1143. async def send_for_platform(
  1144. self,
  1145. logical_platform: Any,
  1146. chat_id: str,
  1147. content: str,
  1148. reply_to: Optional[str] = None,
  1149. metadata: Optional[dict[str, Any]] = None,
  1150. ) -> SendResult:
  1151. """Send to an explicitly advertised logical platform over Relay. Scheduled and
  1152. persisted-home deliveries have no fresh inbound event to populate
  1153. ``_platform_by_chat``. The delivery resolver calls this only after
  1154. ``fronts_platform`` succeeds; repeated here fail-closed."""
  1155. platform_value = str(getattr(logical_platform, "value", logical_platform))
  1156. if not self.fronts_platform(platform_value):
  1157. return SendResult(success=False, error=f"relay does not front platform {platform_value}")
  1158. _sfp_metadata = dict(metadata or {})
  1159. # Gateway-internal interim marker (see send()): strip before the wire.
  1160. _interim = bool(_sfp_metadata.pop("_interim_send", False))
  1161. # The delivery resolver calls THIS method directly, bypassing send() — an
  1162. # open native stream must absorb the turn-final here too.
  1163. seal = await self._absorb_into_open_draft(chat_id, content, _sfp_metadata, _interim)
  1164. if seal is not None:
  1165. return seal
  1166. if self._transport is None:
  1167. return SendResult(success=False, error="no transport")
  1168. self._stamp_slack_unfurl(platform_value, _sfp_metadata)
  1169. result = await self._transport.send_outbound(
  1170. {
  1171. "op": "send",
  1172. "chat_id": chat_id,
  1173. "content": content,
  1174. "reply_to": reply_to,
  1175. # format_hints on the explicit-platform lane too: the cron brief
  1176. # must render blocks exactly like an interactive send.
  1177. "metadata": self._with_scope(
  1178. chat_id, self._with_format_hints_for_platform(platform_value, _sfp_metadata)
  1179. ),
  1180. },
  1181. platform=platform_value,
  1182. )
  1183. if isinstance(result, dict):
  1184. if not result.get("success") and is_egress_decline(result):
  1185. log_decline("send", chat_id, result)
  1186. return _send_result(result, raw_response=result)
  1187. def _format_hints(
  1188. self, descriptor: Optional[CapabilityDescriptor], platform: Optional[str]
  1189. ) -> Optional[dict[str, bool]]:
  1190. """Block-formatting hints for one outbound text frame, or None. The CONNECTOR
  1191. owns the platform API call, so the gateway only signals intent: stamped ONLY
  1192. when (a) the DESTINATION platform's negotiated descriptor advertises
  1193. ``supports_block_formatting`` (an old connector never receives dead metadata)
  1194. and (b) the operator enabled ``platforms.relay.extra.<platform>.rich_blocks`` /
  1195. ``markdown_blocks`` (both default OFF, ``_coerce_flag`` semantics).
  1196. ``descriptor``/``platform`` are the DESTINATION's, never the scalar primary:
  1197. gating on the primary both leaked hints onto platforms that never advertised
  1198. the bit and suppressed them for ones that did."""
  1199. if descriptor is None or not getattr(descriptor, "supports_block_formatting", False):
  1200. return None
  1201. try:
  1202. knob_src = self._relay_platform_extra(str(platform or "").lower())
  1203. except Exception:
  1204. return None
  1205. hints = {knob: True for knob in ("rich_blocks", "markdown_blocks") if self._coerce_flag(knob_src.get(knob), False)}
  1206. return hints or None
  1207. def _stamp_format_hints(
  1208. self,
  1209. descriptor: Optional[CapabilityDescriptor],
  1210. platform: Optional[str],
  1211. metadata: Optional[dict[str, Any]],
  1212. ) -> Optional[dict[str, Any]]:
  1213. """``metadata`` with ``format_hints`` for the DESTINATION (descriptor, platform) stamped, if any."""
  1214. hints = self._format_hints(descriptor, platform)
  1215. if not hints:
  1216. return metadata
  1217. merged = dict(metadata or {})
  1218. merged.setdefault("format_hints", hints)
  1219. return merged
  1220. def _with_format_hints_for_chat(
  1221. self, chat_id: str, metadata: Optional[dict[str, Any]]
  1222. ) -> Optional[dict[str, Any]]:
  1223. """Hints for a chat-addressed send (chat's platform as seen inbound, else the primary)."""
  1224. return self._stamp_format_hints(self._descriptor_for_chat(chat_id), self._chat_platform(chat_id), metadata)
  1225. def _with_format_hints_for_platform(
  1226. self, platform_value: str, metadata: Optional[dict[str, Any]]
  1227. ) -> Optional[dict[str, Any]]:
  1228. """Hints for an explicit-platform send (scheduled/persisted-home lane). Falls
  1229. back to the scalar descriptor only when it IS that platform's — never stamp
  1230. from another platform's capability bit."""
  1231. descriptor = self._negotiated_descriptor(str(platform_value))
  1232. if descriptor is None and self.descriptor.platform == str(platform_value):
  1233. descriptor = self.descriptor
  1234. return self._stamp_format_hints(descriptor, str(platform_value), metadata)
  1235. async def send(
  1236. self,
  1237. chat_id: str,
  1238. content: str,
  1239. reply_to: Optional[str] = None,
  1240. metadata: Optional[dict[str, Any]] = None,
  1241. ) -> SendResult:
  1242. send_metadata = dict(metadata or {})
  1243. explicit_platform = send_metadata.pop("_relay_logical_platform", None)
  1244. # Consumer-declared interim send (commentary, tail flush): NOT the turn-final,
  1245. # so it must never trigger seal-interception (sealing the live stream with
  1246. # interim text orphans the true final into a plain duplicate).
  1247. # Gateway-internal marker; strip before the wire.
  1248. _interim = bool(send_metadata.pop("_interim_send", False))
  1249. # Seal-interception is checked BEFORE the explicit-platform branch: an open
  1250. # stream absorbs the turn-final whichever door it arrives through.
  1251. seal = await self._absorb_into_open_draft(chat_id, content, send_metadata, _interim)
  1252. if seal is not None:
  1253. return seal
  1254. if explicit_platform:
  1255. return await self.send_for_platform(
  1256. explicit_platform, chat_id, content, reply_to=reply_to, metadata=send_metadata or None
  1257. )
  1258. if self._transport is None:
  1259. return SendResult(success=False, error="no transport")
  1260. effective_reply_to = self._prepare_slack_egress(chat_id, reply_to, send_metadata)
  1261. result = await self._outbound(
  1262. chat_id,
  1263. {
  1264. "op": "send",
  1265. "chat_id": chat_id,
  1266. "content": content,
  1267. "reply_to": effective_reply_to,
  1268. "metadata": self._text_metadata(chat_id, send_metadata),
  1269. },
  1270. )
  1271. # Auto-thread routing feedback: when the connector's auto-thread policy routed
  1272. # this send into a thread it just created, the result carries thread_id (+
  1273. # initial name). The conversation was keyed on the PARENT channel, so this is
  1274. # the only place the gateway learns where the reply landed.
  1275. try:
  1276. _at_thread = result.get("thread_id")
  1277. _at_name = result.get("auto_thread_name")
  1278. if _at_thread and _at_name:
  1279. self._auto_thread_by_chat[str(chat_id)] = (str(_at_thread), str(_at_name))
  1280. if len(self._auto_thread_by_chat) > 256:
  1281. self._auto_thread_by_chat.pop(next(iter(self._auto_thread_by_chat)), None)
  1282. except Exception:
  1283. pass
  1284. # Wake the rename lane on EVERY send into this chat: "nowhere new" is an
  1285. # answer it should get now rather than by outlasting a timeout.
  1286. waiter = self._auto_thread_waiters.get(str(chat_id))
  1287. if waiter is not None:
  1288. waiter.set()
  1289. return _send_result(result)
  1290. def auto_thread_info_for_chat(self, chat_id: str) -> Optional[tuple[str, str]]:
  1291. """(thread_id, initial_name) of the connector-created auto-thread for the most
  1292. recent send into *chat_id*, if any (semantic thread-rename lane)."""
  1293. return self._auto_thread_by_chat.get(str(chat_id))
  1294. async def wait_for_auto_thread_info(self, chat_id: str, timeout: float) -> Optional[tuple[str, str]]:
  1295. """``auto_thread_info_for_chat``, but willing to wait for the send. The rename
  1296. lane asks as soon as the session is titled — a whole turn early. Waits for the
  1297. next send into this chat, so a reply the connector didn't auto-thread reports
  1298. its miss immediately; *timeout* is only a backstop for a turn that never sends."""
  1299. info = self.auto_thread_info_for_chat(chat_id)
  1300. if info is not None:
  1301. return info
  1302. key = str(chat_id)
  1303. waiter = self._auto_thread_waiters.get(key)
  1304. if waiter is None:
  1305. waiter = asyncio.Event()
  1306. self._auto_thread_waiters[key] = waiter
  1307. try:
  1308. await asyncio.wait_for(waiter.wait(), timeout)
  1309. except TimeoutError:
  1310. return None
  1311. finally:
  1312. # Only the waiter we installed, and only if no later call replaced it; a
  1313. # fired event must not make the next turn's wait return instantly.
  1314. if self._auto_thread_waiters.get(key) is waiter:
  1315. self._auto_thread_waiters.pop(key, None)
  1316. return self.auto_thread_info_for_chat(chat_id)
  1317. def _resolve_reply_to_for_send(
  1318. self, chat_id: str, reply_to: Optional[str], metadata: Optional[dict[str, Any]],
  1319. ) -> Optional[str]:
  1320. """Suppress the synthetic-DM thread anchor for a Slack DM reply.
  1321. The stream consumer sends a DM reply with ``reply_to`` = the triggering ts
  1322. (its edit anchor); the connector maps a raw reply_to to a Slack thread_ts, so
  1323. the reply would thread under the user's message and lose progressive edit
  1324. streaming. Native ``_resolve_thread_ts`` drops that anchor only when
  1325. ``reply_in_thread`` is off; mirror it: Slack DM + no real
  1326. ``thread_id``/``thread_ts`` + flat mode ⇒ drop. In thread-per-message mode the
  1327. triggering ts IS the thread anchor and the final reply's ONLY threading signal
  1328. (dropping it unconditionally exiled finals to the DM root while progress
  1329. stayed threaded). Removes an anchor, never adds one.
  1330. It does NOT: * regress real-thread streaming — a real thread carries a distinct ``thread_id`` in
  1331. metadata, so the guard leaves ``reply_to`` alone; * regress channel autoThread — a channel/group
  1332. top-level reply carries ``thread_id`` (the message's own ts) in metadata when threading is on, so it
  1333. is left alone; and a non-DM chat is never matched here. See #18859.
  1334. """
  1335. if reply_to is None:
  1336. return None
  1337. md = metadata or {}
  1338. if (
  1339. self._platform_by_chat.get(str(chat_id)) != _SLACK
  1340. or self._chat_type_by_chat.get(str(chat_id)) != "dm"
  1341. or md.get("thread_id")
  1342. or md.get("thread_ts")
  1343. ):
  1344. return reply_to
  1345. return reply_to if self._effective_reply_in_thread() else None
  1346. def _apply_slack_thread_anchor(
  1347. self,
  1348. chat_id: str,
  1349. reply_to: Optional[str],
  1350. metadata: dict[str, Any],
  1351. *,
  1352. mirror_key: str = "reply_to_message_id",
  1353. ) -> Optional[str]:
  1354. """Resolve the outbound Slack thread anchor for ONE egress frame — the single
  1355. choke point for text (``send``) and media (``_send_media``): (1) mode gate via
  1356. ``_resolve_reply_to_for_send``; (2) when the anchor is dropped, strip the
  1357. mirrored ``metadata.reply_to_message_id`` too, or the connector threads on it;
  1358. (3) the connector's Slack sender THREADS ON METADATA ONLY (``threadTs()`` never
  1359. reads the frame's ``reply_to``), so a surviving anchor is promoted into
  1360. ``metadata.thread_id``. ``metadata`` is mutated in place."""
  1361. effective_reply_to = self._resolve_reply_to_for_send(chat_id, reply_to, metadata)
  1362. if effective_reply_to is None and reply_to is not None:
  1363. metadata.pop(mirror_key, None)
  1364. if (
  1365. effective_reply_to is not None
  1366. and self._platform_by_chat.get(str(chat_id)) == _SLACK
  1367. and not (metadata.get("thread_id") or metadata.get("thread_ts"))
  1368. ):
  1369. metadata["thread_id"] = str(effective_reply_to)
  1370. return effective_reply_to
  1371. def _prepare_slack_egress(
  1372. self, chat_id: str, reply_to: Optional[str], metadata: dict[str, Any]
  1373. ) -> Optional[str]:
  1374. """Text/media egress prep: Slack thread anchor (DM replies post flat at the DM
  1375. root, native _resolve_thread_ts parity) + unfurl hints; mutates ``metadata``."""
  1376. effective_reply_to = self._apply_slack_thread_anchor(chat_id, reply_to, metadata)
  1377. self._stamp_slack_unfurl(self._chat_platform(chat_id), metadata)
  1378. return effective_reply_to
  1379. def _with_status_thread_anchor(
  1380. self, chat_id: str, metadata: Optional[dict[str, Any]], anchor: Optional[str] = None
  1381. ) -> dict[str, Any]:
  1382. """Copy ``metadata`` with the typing/status thread anchor applied. Slack's status
  1383. line is THREAD-scoped and a top-level DM turn's metadata names no thread, so its
  1384. status sits on ``anchor``, the turn's own message. A turn fixes it at start
  1385. (``status_metadata_for_turn``) and its refreshes and clear reuse it: the clear MUST
  1386. target the thread the heartbeat set or the status sticks. Without one (event-less
  1387. callers) it falls back to the chat's latest inbound ts, which a later message moves."""
  1388. md = dict(metadata or {})
  1389. if (
  1390. not (md.get("thread_id") or md.get("thread_ts"))
  1391. and self._platform_by_chat.get(str(chat_id)) == _SLACK
  1392. and self._chat_type_by_chat.get(str(chat_id)) == "dm"
  1393. ):
  1394. anchor = anchor or self._last_inbound_ts_by_chat.get(str(chat_id))
  1395. if anchor:
  1396. md["thread_id"] = str(anchor)
  1397. return md
  1398. def status_metadata_for_turn(self, chat_id: str, anchor: str, metadata: Optional[dict]) -> dict[str, Any]:
  1399. """``helpers.typing_metadata_for_turn`` hook: the turn's typing metadata, status anchor fixed."""
  1400. return self._with_status_thread_anchor(chat_id, metadata, anchor)
  1401. async def edit_message(
  1402. self,
  1403. chat_id: str,
  1404. message_id: str,
  1405. content: str,
  1406. *,
  1407. finalize: bool = False,
  1408. metadata: Optional[dict[str, Any]] = None,
  1409. ) -> SendResult:
  1410. """Edit a relayed message through the connector-owned platform API."""
  1411. if self._transport is None:
  1412. return SendResult(success=False, error="no transport")
  1413. result = await self._outbound(
  1414. chat_id,
  1415. {
  1416. "op": "edit",
  1417. "chat_id": chat_id,
  1418. "message_id": message_id,
  1419. "content": content,
  1420. "metadata": self._text_metadata(chat_id, metadata),
  1421. },
  1422. )
  1423. # P5(b): carry the structured body. THREE separate callers read a bare
  1424. # edit failure as "editing is unavailable" and re-send the content as a
  1425. # NEW message to the same chat (stream edit-fallback, queued-response
  1426. # reconciliation, task-card fallback edit). The edit lane is the ninth
  1427. # place a decline could be laundered into a different op.
  1428. return SendResult(
  1429. success=bool(result.get("success")), message_id=result.get("message_id") or message_id,
  1430. error=result.get("error"),
  1431. raw_response=result,
  1432. )
  1433. async def delete_message(self, chat_id: str, message_id: str) -> bool:
  1434. """Delete a relayed message (the stream consumer's fresh-final cleanup). Gated
  1435. on the descriptor advertising ``delete``: older connectors return False so
  1436. cleanup degrades to leaving the preview in place."""
  1437. if self._transport is None:
  1438. return False
  1439. if "delete" not in (self._descriptor_for_chat(str(chat_id)).supported_ops or ()):
  1440. return False
  1441. try:
  1442. result = await self._outbound(
  1443. chat_id,
  1444. {
  1445. "op": "delete",
  1446. "chat_id": chat_id,
  1447. "message_id": message_id,
  1448. "metadata": self._with_scope(chat_id, {}),
  1449. },
  1450. )
  1451. except Exception:
  1452. logger.debug("relay delete_message failed", exc_info=True)
  1453. return False
  1454. return bool(result.get("success"))
  1455. async def send_typing(self, chat_id: str, metadata=None) -> None:
  1456. """Egress a typing indicator (the base ``_keep_typing`` tick) as the ``typing``
  1457. op. Best-effort and one-shot: Discord/Telegram indicators self-expire; Slack
  1458. Assistant status persists, so ``stop_typing`` sends an explicit clear for
  1459. Slack only."""
  1460. if self._transport is None:
  1461. return
  1462. # Rich status parity: carry run.py's per-tool phrase as the frame's content
  1463. # (rendered on assistant.threads.setStatus). Absent => omit content and the
  1464. # connector uses its default heartbeat. NEVER send empty-string content here:
  1465. # on Slack that is the CLEAR request.
  1466. phrase = getattr(self, "_status_text", {}).get(str(chat_id))
  1467. await self._typing_frame(chat_id, metadata, str(phrase) if phrase else None, "send_typing")
  1468. async def stop_typing(self, chat_id: str, metadata: Optional[dict[str, Any]] = None) -> None:
  1469. """Forward an explicit typing/status clear (empty ``content``) — Slack only:
  1470. other relay senders have one-shot heartbeats, where an empty heartbeat would
  1471. re-trigger typing at completion. A connector older than gateway-gateway #154
  1472. hardcodes the typing status and would SET it on a clear frame — deploy the
  1473. connector first."""
  1474. if self._transport is None or self._platform_by_chat.get(str(chat_id)) != _SLACK:
  1475. return
  1476. await self._typing_frame(chat_id, metadata, "", "stop_typing")
  1477. async def _typing_frame(
  1478. self, chat_id: str, metadata: Optional[dict[str, Any]], content: Optional[str], lane: str
  1479. ) -> None:
  1480. """One ``typing`` frame (``content`` None = omit; "" = Slack clear). Cosmetic: never raises."""
  1481. # Thread anchor for the status surface. Slack's status line ("is thinking…" in the thread's replies
  1482. # footer — works with plain chat:write, confirmed on native no-assistant bots) is THREAD-only: the
  1483. # connector's typing case no-ops without a thread_ts. A top-level DM turn's typing metadata already
  1484. # names its own message (fixed at turn start); see _with_status_thread_anchor for the fallback.
  1485. md = self._with_status_thread_anchor(chat_id, metadata)
  1486. frame: dict[str, Any] = {"op": "typing", "chat_id": chat_id, "metadata": self._with_scope(chat_id, md)}
  1487. if content is not None:
  1488. frame["content"] = content
  1489. try:
  1490. await self._outbound(chat_id, frame)
  1491. except Exception:
  1492. logger.debug("relay %s failed for %s", lane, chat_id, exc_info=True)
  1493. async def get_chat_info(self, chat_id: str) -> dict[str, Any]:
  1494. # Op-gated so a legacy connector (which would only answer "unsupported op")
  1495. # gets the same local fallback without a round trip.
  1496. if self._transport is None or not self.descriptor.supports_op("get_chat_info"):
  1497. return {"name": chat_id, "type": "dm"}
  1498. return await self._transport.get_chat_info(chat_id)
  1499. async def send_follow_up(
  1500. self, session_key: str, kind: str, content: str, metadata: Optional[dict[str, Any]] = None,
  1501. ) -> SendResult:
  1502. """Send via a shared-identity capability bound to a session. The gateway never
  1503. holds the credential: it names the session and the capability ``kind``; the
  1504. connector resolves the value from its vault and egresses (enforcing tenant)."""
  1505. if self._transport is None:
  1506. return SendResult(success=False, error="no transport")
  1507. # `kind` is platform-prefixed ("discord.interaction_token"): tag the frame
  1508. # with that platform when we front it; otherwise the connector's session
  1509. # default routes it.
  1510. prefix = kind.split(".", 1)[0] if kind and "." in kind else None
  1511. follow_up_platform = prefix if prefix and self.fronts_platform(prefix) else None
  1512. follow_up_metadata = dict(metadata or {})
  1513. # The session key names the profile namespace the interaction ran under; carry it so the
  1514. # connector's next passthrough_forward for this interaction routes to the same profile.
  1515. if not follow_up_metadata.get("profile"):
  1516. profile = _profile_from_session_key(session_key)
  1517. if profile:
  1518. follow_up_metadata["profile"] = profile
  1519. result = await self._transport.send_follow_up(
  1520. {
  1521. "op": "follow_up",
  1522. "session_key": session_key,
  1523. "kind": kind,
  1524. "content": content,
  1525. "metadata": follow_up_metadata,
  1526. },
  1527. platform=follow_up_platform,
  1528. )
  1529. # CARRY THE STRUCTURED DECLINE. This lane is addressed by `session_key`,
  1530. # not `chat_id`, so it has no latch identity — the latch is per chat and
  1531. # inventing one from a session key would be exactly the text-derived
  1532. # identity that blocker 2 was about. What it must NOT do is discard the
  1533. # connector's verdict: dropping `raw_response` is precisely how the
  1534. # `edit_message` lane laundered declines into a plain send.
  1535. if isinstance(result, dict) and not result.get("success") and is_egress_decline(result):
  1536. log_decline("follow_up", session_key, result)
  1537. return _send_result(result, raw_response=result)
  1538. # ── Phase 2 media ─────────────────────────────────────────────────────
  1539. def _get_media_client(self) -> Optional[RelayMediaClient]:
  1540. """Lazily build the authenticated /relay/media client from the SAME dial URL and
  1541. per-gateway creds the WS uses; None when unavailable (media lanes then degrade
  1542. to their pre-media fallbacks)."""
  1543. if self._media_client is not None:
  1544. return self._media_client
  1545. try:
  1546. from gateway.relay import relay_connection_auth, relay_url
  1547. from gateway.relay.media import media_base_url
  1548. url = relay_url()
  1549. gateway_id, secret = relay_connection_auth()
  1550. if not url:
  1551. return None
  1552. client = RelayMediaClient(media_base_url(url), gateway_id, secret)
  1553. if not client.enabled:
  1554. return None
  1555. self._media_client = client
  1556. return client
  1557. except Exception:
  1558. logger.debug("relay media client init failed", exc_info=True)
  1559. return None
  1560. async def _send_media(
  1561. self,
  1562. chat_id: str,
  1563. *,
  1564. media_kind: str,
  1565. source: str,
  1566. source_is_path: bool,
  1567. caption: Optional[str] = None,
  1568. filename: Optional[str] = None,
  1569. reply_to: Optional[str] = None,
  1570. metadata: Optional[dict[str, Any]] = None,
  1571. ) -> Optional[SendResult | _MediaNotDelivered]:
  1572. """Egress one media object via the connector's ``send_media`` op. ``source`` is
  1573. a LOCAL path (uploaded to /relay/media first — the connector cannot reach our
  1574. filesystem) or an already-public URL (passed through). None when the lane is
  1575. unavailable (op not advertised, no transport, no media client) so each caller
  1576. falls back to its pre-media behaviour; ``_MediaNotDelivered`` when the lane was
  1577. there but a LOCAL file never reached the platform (upload failed after its
  1578. retries, connector decline/transport failure): the caller still falls back, but
  1579. reports the send failed (``_send_local_media``)."""
  1580. if self._transport is None or not self.descriptor.supports_op("send_media"):
  1581. return None
  1582. source_url = source
  1583. if source_is_path:
  1584. client = self._get_media_client()
  1585. if client is None:
  1586. return None
  1587. uploaded, why = await client.upload_with_error(source, filename=filename)
  1588. if not uploaded:
  1589. return _MediaNotDelivered(f"relay media upload failed: {why}")
  1590. source_url = uploaded
  1591. # Same Slack thread-anchor contract as the text lane: media frames go through
  1592. # the connector's Slack sender too (threadTs() reads metadata only).
  1593. media_metadata: dict[str, Any] = dict(metadata or {})
  1594. effective_reply_to = self._prepare_slack_egress(chat_id, reply_to, media_metadata)
  1595. action: dict[str, Any] = {
  1596. "op": "send_media",
  1597. "chat_id": chat_id,
  1598. "media_kind": media_kind,
  1599. "source_url": source_url,
  1600. "content": caption or "",
  1601. "reply_to": effective_reply_to,
  1602. "metadata": self._with_scope(chat_id, media_metadata),
  1603. }
  1604. if filename:
  1605. action["filename"] = filename
  1606. # Capacity decline -> caller's fallback notice; AUTHORIZATION decline never degrades.
  1607. result = await self._gated_op(chat_id, action, surface_declines=True, surface_ambiguous=True)
  1608. if result is None:
  1609. return _MediaNotDelivered("connector did not deliver the attachment") if source_is_path else None
  1610. if result.get("ambiguous"): # ack lost: possibly delivered (as cron's live-send timeout); no notice/re-send
  1611. logger.warning("relay send_media to %s unconfirmed (ack lost): %s", chat_id, result.get("error"))
  1612. return SendResult(success=True, raw_response={"ambiguous": True, "error": result.get("error")})
  1613. if not result.get("success"):
  1614. # An AUTHORIZATION refusal, surfaced by _gated_op. Returning None
  1615. # would hand the caller back to its fallback — a DIFFERENT op
  1616. # against the SAME destination the connector just refused. Report
  1617. # a failed lane instead, carrying the decline verbatim.
  1618. return SendResult(
  1619. success=False, error=decline_error(result), raw_response=result
  1620. )
  1621. return SendResult(success=True, message_id=result.get("message_id"), raw_response=result)
  1622. # Each media override tries the native ``send_media`` lane, then falls back to
  1623. # the base adapter's text/URL behaviour when the lane is unavailable.
  1624. async def send_image(
  1625. self,
  1626. chat_id: str,
  1627. image_url: str,
  1628. caption: Optional[str] = None,
  1629. reply_to: Optional[str] = None,
  1630. metadata: Optional[dict[str, Any]] = None,
  1631. ) -> SendResult:
  1632. result = await self._send_media(
  1633. chat_id, media_kind="image", source=image_url, source_is_path=False,
  1634. caption=caption, reply_to=reply_to, metadata=metadata,
  1635. )
  1636. return result if result is not None else await super().send_image(
  1637. chat_id, image_url, caption=caption, reply_to=reply_to, metadata=metadata
  1638. )
  1639. # The local-file overrides share ``_send_local_media`` (send_media lane, else the base
  1640. # fallback notice; a file the lane dropped is reported as a failed send).
  1641. async def send_image_file(self, chat_id: str, image_path: str, caption: Optional[str] = None,
  1642. reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None,
  1643. **kwargs) -> SendResult:
  1644. return await self._send_local_media(chat_id, "image", image_path, caption, reply_to, metadata, partial(
  1645. super().send_image_file, chat_id, image_path, caption=caption, reply_to=reply_to, metadata=metadata,
  1646. **kwargs))
  1647. async def send_voice(self, chat_id: str, audio_path: str, caption: Optional[str] = None,
  1648. reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None,
  1649. **kwargs) -> SendResult:
  1650. return await self._send_local_media(chat_id, "voice", audio_path, caption, reply_to, metadata, partial(
  1651. super().send_voice, chat_id, audio_path, caption=caption, reply_to=reply_to, metadata=metadata,
  1652. **kwargs))
  1653. async def send_video(self, chat_id: str, video_path: str, caption: Optional[str] = None,
  1654. reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None,
  1655. **kwargs) -> SendResult:
  1656. return await self._send_local_media(chat_id, "video", video_path, caption, reply_to, metadata, partial(
  1657. super().send_video, chat_id, video_path, caption=caption, reply_to=reply_to, metadata=metadata,
  1658. **kwargs))
  1659. async def send_document(self, chat_id: str, file_path: str, caption: Optional[str] = None,
  1660. file_name: Optional[str] = None, reply_to: Optional[str] = None,
  1661. metadata: Optional[dict[str, Any]] = None, **kwargs) -> SendResult:
  1662. return await self._send_local_media(chat_id, "document", file_path, caption, reply_to, metadata, partial(
  1663. super().send_document, chat_id, file_path, caption=caption, file_name=file_name, reply_to=reply_to,
  1664. metadata=metadata, **kwargs), filename=file_name)
  1665. async def _send_local_media(
  1666. self, chat_id: str, media_kind: str, path: str, caption: Optional[str], reply_to: Optional[str],
  1667. metadata: Optional[dict[str, Any]], fallback: Callable[[], Awaitable[SendResult]],
  1668. filename: Optional[str] = None,
  1669. ) -> SendResult:
  1670. """One local file through the send_media lane, else ``fallback`` (the base caption +
  1671. "couldn't send" notice). When the lane was available but the file still never arrived,
  1672. the notice goes out exactly as before, yet the send is reported FAILED: cron, the
  1673. send_message tool and the turn tracker must not record a dropped attachment as sent.
  1674. ``failure_notice_sent`` stops the turn dispatcher from posting a second notice."""
  1675. result = await self._send_media(
  1676. chat_id, media_kind=media_kind, source=path, source_is_path=True, caption=caption,
  1677. filename=filename, reply_to=reply_to, metadata=metadata,
  1678. )
  1679. if isinstance(result, SendResult):
  1680. return result
  1681. shown = await fallback()
  1682. if result is None:
  1683. return shown
  1684. return SendResult(
  1685. success=False, message_id=shown.message_id, error=f"attachment not delivered: {result.reason}",
  1686. raw_response={"failure_notice_sent": bool(shown.success), "fallback": shown.raw_response},
  1687. )
  1688. # ── Phase 3 interactive: prompt + react ──────────────────────────────
  1689. def _mint_prompt(
  1690. self, kind: str, state: dict[str, Any], timeout_s: float = 3600.0
  1691. ) -> str:
  1692. """Register a pending prompt and return its id (``<owner nonce>.<8 hex>``).
  1693. Expiry is enforced gateway-side on consumption (_pop_prompt); the wire's
  1694. timeout_s is advisory. The nonce marks the minting process so a sibling
  1695. gateway receiving the fanned-out answer stays quiet. Both segments use the
  1696. connector codec's alphabet ([A-Za-z0-9_.-], <=32)."""
  1697. prompt_id = f"{self._prompt_owner_nonce}.{secrets.token_hex(4)}"
  1698. self._pending_prompts[prompt_id] = {**state, "kind": kind, "expires_at": time.time() + timeout_s}
  1699. # Opportunistic sweep so abandoned prompts can't accumulate.
  1700. now = time.time()
  1701. for stale in [k for k, v in self._pending_prompts.items() if v.get("expires_at", 0) < now]:
  1702. self._pending_prompts.pop(stale, None)
  1703. return prompt_id
  1704. def _minted_here(self, prompt_id: str) -> bool:
  1705. """True when this process minted ``prompt_id``. Ids without a ``.`` segment
  1706. predate the owner nonce (in-flight across an in-place upgrade) and are ours."""
  1707. head, sep, _ = str(prompt_id).partition(".")
  1708. return head == self._prompt_owner_nonce if sep else True
  1709. def _pop_prompt(self, prompt_id: str) -> Optional[dict[str, Any]]:
  1710. """Consume a pending prompt: one answer wins, expired entries miss."""
  1711. state = self._pending_prompts.pop(str(prompt_id), None)
  1712. if not state or state.get("expires_at", 0) < time.time():
  1713. return None
  1714. return state
  1715. def _note_prompt_resolved(self, prompt_id: str) -> None:
  1716. """Remember that this process answered ``prompt_id`` (bounded FIFO: a repeat is
  1717. only interesting while a redelivery/double tap can arrive)."""
  1718. self._resolved_prompts[str(prompt_id)] = time.time()
  1719. while len(self._resolved_prompts) > _RESOLVED_PROMPT_MEMORY:
  1720. self._resolved_prompts.popitem(last=False)
  1721. async def _send_prompt(
  1722. self,
  1723. chat_id: str,
  1724. *,
  1725. prompt_kind: str,
  1726. text: str,
  1727. prompt_id: str,
  1728. options: list,
  1729. reply_to: Optional[str] = None,
  1730. metadata: Optional[dict[str, Any]] = None,
  1731. timeout_s: Optional[int] = None,
  1732. ) -> Optional[SendResult]:
  1733. """Egress one `prompt` op; None when the lane is unavailable (the caller falls
  1734. back to its numbered-text base behaviour). Prompt metadata is forwarded
  1735. VERBATIM: the threading mode is decided in exactly one place — run.py's
  1736. _resolve_progress_thread_id (flat mode suppresses the synthetic self-anchor
  1737. there; thread mode stamps the turn's thread)."""
  1738. action: dict[str, Any] = {
  1739. "op": "prompt",
  1740. "chat_id": chat_id,
  1741. "content": text,
  1742. "prompt_kind": prompt_kind,
  1743. "prompt_id": prompt_id,
  1744. "options": options,
  1745. "reply_to": self._resolve_reply_to_for_send(chat_id, reply_to, metadata),
  1746. "metadata": self._with_scope(chat_id, metadata),
  1747. }
  1748. if timeout_s is not None:
  1749. action["timeout_s"] = int(timeout_s)
  1750. result = await self._gated_op(chat_id, action, surface_declines=True)
  1751. if result is None:
  1752. return None
  1753. if not result.get("success"):
  1754. # An AUTHORIZATION refusal, surfaced by _gated_op. Returning None
  1755. # would hand the caller back to its fallback — a DIFFERENT op
  1756. # against the SAME destination the connector just refused. Report
  1757. # a failed lane instead, carrying the decline verbatim.
  1758. return SendResult(
  1759. success=False, error=decline_error(result), raw_response=result
  1760. )
  1761. return SendResult(success=True, message_id=result.get("message_id"), raw_response=result)
  1762. async def _mint_and_send_prompt(
  1763. self,
  1764. kind: str,
  1765. state: dict[str, Any],
  1766. chat_id: str,
  1767. *,
  1768. prompt_kind: str,
  1769. text: str,
  1770. options: list,
  1771. metadata: Optional[dict[str, Any]],
  1772. ) -> Optional[SendResult]:
  1773. """Register + egress a prompt; unregisters and returns None when the lane is unavailable."""
  1774. prompt_id = self._mint_prompt(kind, {**state, "chat_id": str(chat_id)})
  1775. result = await self._send_prompt(
  1776. chat_id, prompt_kind=prompt_kind, text=text, prompt_id=prompt_id, options=options,
  1777. metadata=metadata,
  1778. )
  1779. if result is None or not getattr(result, "success", False):
  1780. # P5(b): a DECLINE now returns a failed SendResult rather than
  1781. # None, and the registration must come down on that path too. A
  1782. # prompt card the connector refused never rendered, so leaving it
  1783. # pending lets the user's next unrelated message be captured as the
  1784. # answer to a prompt they never saw.
  1785. self._pending_prompts.pop(prompt_id, None)
  1786. return result
  1787. _PROMPT_UNAVAILABLE = SendResult(success=False, error="relay prompt op unavailable")
  1788. _EA_CMD_BUDGET = 1500
  1789. async def _send_exec_approval_prompt(self, prompt: ExecApprovalPrompt) -> SendResult:
  1790. """Native-button exec approval over the relay (the press resolves via
  1791. tools.approval.resolve_gateway_approval). When the lane is unavailable the send FAILS
  1792. (success=False) so run.py's button→text fallback runs."""
  1793. options = [{"id": choice, "label": label, **({"style": style} if style else {})}
  1794. for label, choice, style in prompt.actions]
  1795. result = await self._mint_and_send_prompt(
  1796. "exec_approval", {"session_key": prompt.session_key, "request_id": prompt.request_id},
  1797. prompt.chat_id, prompt_kind="approval",
  1798. text=prompt.text, options=options, metadata=prompt.metadata,
  1799. )
  1800. return result if result is not None else self._PROMPT_UNAVAILABLE
  1801. async def send_slash_confirm(
  1802. self,
  1803. chat_id: str,
  1804. title: str,
  1805. message: str,
  1806. session_key: str,
  1807. confirm_id: str,
  1808. metadata: Optional[dict[str, Any]] = None,
  1809. ) -> SendResult:
  1810. """Three-button slash-command confirmation over the relay (resolves via
  1811. tools.slash_confirm.resolve; success=False falls back to text-intercept)."""
  1812. options = [
  1813. {"id": "once", "label": t("platform.relay.confirm_approve_once"), "style": "primary"},
  1814. {"id": "always", "label": t("platform.relay.confirm_always_approve")},
  1815. {"id": "cancel", "label": t("platform.relay.confirm_cancel"), "style": "danger"},
  1816. ]
  1817. result = await self._mint_and_send_prompt(
  1818. "slash_confirm", {"session_key": session_key, "confirm_id": confirm_id}, chat_id,
  1819. prompt_kind="approval", text=f"**{title}**\n\n{message}" if title else message,
  1820. options=options, metadata=metadata,
  1821. )
  1822. return result if result is not None else self._PROMPT_UNAVAILABLE
  1823. async def send_clarify(
  1824. self,
  1825. chat_id: str,
  1826. question: str,
  1827. choices: Optional[list],
  1828. clarify_id: str,
  1829. session_key: str,
  1830. metadata: Optional[dict[str, Any]] = None,
  1831. ) -> SendResult:
  1832. """Native-button clarify over the relay. A press resolves with the CHOICE TEXT
  1833. (never the option id); "Other" flips to text-capture. Option ids are
  1834. positional (c0..cN / other) — choice text is arbitrary UTF-8 and would blow
  1835. the 64-byte callback budget. Open-ended clarifies and unavailable lanes fall
  1836. back to base."""
  1837. if choices and self.descriptor.supports_op("prompt"):
  1838. options = [{"id": f"c{i}", "label": str(choice)[:75]} for i, choice in enumerate(choices)]
  1839. options.append({"id": "other", "label": t("platform.relay.prompt_other")})
  1840. result = await self._mint_and_send_prompt(
  1841. "clarify",
  1842. {
  1843. "session_key": session_key,
  1844. "clarify_id": clarify_id,
  1845. "choices": [str(c) for c in choices],
  1846. },
  1847. chat_id,
  1848. prompt_kind="clarify",
  1849. text=f"❓ {question}",
  1850. options=options,
  1851. metadata=metadata,
  1852. )
  1853. if result is not None:
  1854. return result
  1855. return await super().send_clarify(
  1856. chat_id, question, choices, clarify_id, session_key, metadata=metadata
  1857. )
  1858. async def _consume_prompt_response(self, event) -> bool:
  1859. """Route an inbound prompt_response to its waiting primitive; True when the
  1860. event was a prompt answer (consumed — never dispatched as chat). EVERY prompt
  1861. answer is consumed, whoever owns it: a sibling's prompt (the connector fans the
  1862. press to every gateway of the tenant; falling through produced a wall of
  1863. "Unknown command"), a repeat answer (first one won), or our own expired/unknown
  1864. prompt (answered with a short expiry notice — option ids are not commands)."""
  1865. pr = getattr(event, "prompt_response", None)
  1866. if not isinstance(pr, dict):
  1867. return False
  1868. prompt_id = str(pr.get("prompt_id") or "")
  1869. option_id = str(pr.get("option_id") or "")
  1870. if not prompt_id or not option_id:
  1871. return False
  1872. if not self._minted_here(prompt_id):
  1873. logger.debug(
  1874. "relay prompt_response %s (option=%s) belongs to another gateway instance — ignoring",
  1875. prompt_id,
  1876. option_id,
  1877. )
  1878. return True
  1879. if prompt_id in self._resolved_prompts:
  1880. logger.debug(
  1881. "relay prompt_response %s (option=%s) already resolved — ignoring repeat", prompt_id, option_id
  1882. )
  1883. return True
  1884. state = self._pop_prompt(prompt_id)
  1885. if state is None:
  1886. logger.info("relay prompt_response for unknown/expired prompt %s (option=%s)", prompt_id, option_id)
  1887. await self._notify_prompt_expired(event)
  1888. return True
  1889. self._note_prompt_resolved(prompt_id)
  1890. kind = state.get("kind")
  1891. chat_id = str(state.get("chat_id") or getattr(event.source, "chat_id", ""))
  1892. handler = _PROMPT_RESOLVERS.get(kind)
  1893. try:
  1894. if handler is None:
  1895. logger.warning("relay prompt_response with unknown kind %r", kind)
  1896. else:
  1897. # Acks are fire-and-forget: we are ON the read loop here (see
  1898. # _send_lifecycle_ack) and awaiting a send would self-deadlock.
  1899. await handler(self, state, option_id, chat_id, self._prompt_reply_metadata(event))
  1900. except Exception:
  1901. logger.warning("relay prompt_response resolution failed", exc_info=True)
  1902. return True
  1903. async def _resolve_exec_approval(self, state, option_id, chat_id, ack_meta) -> None:
  1904. from tools.approval import resolve_gateway_approval_card
  1905. choice = option_id if option_id in _EXEC_APPROVAL_LABELS else "deny"
  1906. count = resolve_gateway_approval_card(str(state.get("session_key") or ""), choice, state.get("request_id"))
  1907. label = _EXEC_APPROVAL_LABELS[choice] if count else "⌛ Approval expired — no command was waiting."
  1908. # In-channel ack preserves the audit trail the native edit gives (the
  1909. # connector's prompt message can't be edited cross-platform yet).
  1910. self._send_lifecycle_ack(chat_id, label, ack_meta)
  1911. if count:
  1912. self.resume_typing_for_chat(chat_id)
  1913. async def _resolve_slash_confirm(self, state, option_id, chat_id, ack_meta) -> None:
  1914. from tools import slash_confirm as slash_confirm_mod
  1915. choice = option_id if option_id in _SLASH_CONFIRM_LABELS else "cancel"
  1916. result_text = await slash_confirm_mod.resolve(
  1917. str(state.get("session_key") or ""), str(state.get("confirm_id") or ""), choice
  1918. )
  1919. self._send_lifecycle_ack(chat_id, _SLASH_CONFIRM_LABELS[choice], ack_meta)
  1920. if result_text:
  1921. self._send_lifecycle_ack(chat_id, str(result_text), ack_meta)
  1922. async def _resolve_clarify(self, state, option_id, chat_id, ack_meta) -> None:
  1923. from tools.clarify_gateway import mark_awaiting_text, resolve_gateway_clarify
  1924. clarify_id = str(state.get("clarify_id") or "")
  1925. if option_id == "other":
  1926. mark_awaiting_text(clarify_id)
  1927. self._send_lifecycle_ack(chat_id, "✏️ Type your answer:", ack_meta)
  1928. return
  1929. choices = state.get("choices") or []
  1930. try:
  1931. idx = int(option_id[1:]) if option_id.startswith("c") else -1
  1932. except ValueError:
  1933. idx = -1
  1934. if 0 <= idx < len(choices):
  1935. resolve_gateway_clarify(clarify_id, str(choices[idx]))
  1936. self._send_lifecycle_ack(chat_id, f"✅ {choices[idx]}", ack_meta)
  1937. else:
  1938. # Unmappable option: flip to text capture (never dead-end a clarify).
  1939. mark_awaiting_text(clarify_id)
  1940. def _send_lifecycle_ack(self, chat_id: str, text: str, metadata: dict[str, Any]) -> None:
  1941. """Fire-and-forget a prompt-lifecycle ack from read-loop context.
  1942. _consume_prompt_response executes ON the transport read loop; an ``await
  1943. self.send(...)`` there is a SELF-DEADLOCK (send() blocks on an outbound_result
  1944. future only the read loop can resolve) — every button tap wedged the transport
  1945. for the full outbound timeout. Acks are cosmetic, so they ride a background
  1946. task; failures log at debug. The task ref is retained (asyncio holds tasks weakly)."""
  1947. async def _ack() -> None:
  1948. try:
  1949. await self.send(chat_id, text, metadata=metadata)
  1950. except Exception:
  1951. logger.debug("relay lifecycle ack failed", exc_info=True)
  1952. task = asyncio.create_task(_ack(), name="relay-lifecycle-ack")
  1953. self._lifecycle_ack_tasks.add(task)
  1954. task.add_done_callback(self._lifecycle_ack_tasks.discard)
  1955. async def _notify_prompt_expired(self, event) -> None:
  1956. """Tell the presser their prompt is no longer waiting (owning gateway only, best-effort)."""
  1957. chat_id = str(getattr(event.source, "chat_id", "") or "")
  1958. if not chat_id:
  1959. return
  1960. self._send_lifecycle_ack(
  1961. chat_id,
  1962. t("platform.relay.prompt_expired"),
  1963. self._prompt_reply_metadata(event),
  1964. )
  1965. def _prompt_reply_metadata(self, event) -> dict[str, Any]:
  1966. """Thread metadata so prompt acks land where the prompt lives. Marked INTERIM:
  1967. acks fire while the approval turn's OWN draft stream is open and carry only
  1968. placement metadata, so send()'s single-open-stream fallback sealed the live
  1969. draft with the ack text (frozen stream + duplicate final on every approval turn)."""
  1970. meta: dict[str, Any] = {"_interim_send": True}
  1971. thread_id = getattr(event.source, "thread_id", None)
  1972. if thread_id:
  1973. meta["thread_id"] = str(thread_id)
  1974. return meta
  1975. # ── Phase 3 ack lifecycle (in-progress → outcome reaction) ───────────────
  1976. # Telegram accepts only a CURATED reaction vocabulary — the 73 emoji listed
  1977. # on `ReactionTypeEmoji` (https://core.telegram.org/bots/api#reactiontypeemoji,
  1978. # "Reaction emoji. Currently, it can be one of …"). 👀 (U+1F440) is in that
  1979. # set; ✅ (U+2705) and ❌ (U+274C) are NOT. So on Telegram the in-progress
  1980. # ack landed and every completion ack was rejected by the Bot API — the
  1981. # `turn_ack_reaction_lifecycle` finding ("👀 lands and is removed on
  1982. # completion; the ✅ completion reaction never lands"). Because a react
  1983. # failure is deliberately cosmetic (`_react` is best-effort, logged at
  1984. # debug), it failed silently on every single Telegram turn.
  1985. #
  1986. # 👍/👎 are both in Telegram's set and carry the same success/failure sense.
  1987. # Platforms with free-form reaction vocabularies (Slack, Discord, Matrix,
  1988. # Signal) keep ✅/❌, which read better and are what their users already see.
  1989. # Per-platform divergence here follows `_descriptor_for_chat`'s precedent:
  1990. # platform capabilities genuinely differ, so one hardcoded set cannot serve
  1991. # every lane a multi-platform gateway fronts.
  1992. _ACK_EMOJI_DEFAULT = ("👀", "✅", "❌")
  1993. _ACK_EMOJI_BY_PLATFORM = {
  1994. "telegram": ("👀", "👍", "👎"),
  1995. }
  1996. # `_event_from_wire` maps an absent OR unknown wire platform to
  1997. # `Platform.RELAY`, so an unresolved lane arrives as the truthy string
  1998. # "relay", never as "". Treating only "" as unresolved makes the fallback
  1999. # dead code and silently serves ✅ to a Telegram-primary gateway whose
  2000. # connector did not stamp the platform.
  2001. _ACK_PLATFORM_UNRESOLVED = frozenset({"", "relay"})
  2002. def _ack_emoji(self, event, chat_id) -> tuple:
  2003. """(in_progress, success, failure) for the lane this event arrived on.
  2004. Prefers the EVENT's own platform: an ack always follows an inbound
  2005. event, so the platform is on hand and needs no cache. Falls back to the
  2006. chat's lane as seen inbound, then to the descriptor's primary platform.
  2007. Each candidate is checked in turn because any of them can be the
  2008. placeholder "relay", which resolves nothing.
  2009. `Platform` is a plain `Enum`, so `str()` on a member yields
  2010. "Platform.TELEGRAM", not "telegram" — read `.value` first or every
  2011. lookup misses and silently falls back to the default set.
  2012. """
  2013. for candidate in (
  2014. getattr(getattr(event, "source", None), "platform", None),
  2015. self._platform_by_chat.get(str(chat_id)),
  2016. getattr(self.descriptor, "platform", None),
  2017. ):
  2018. name = str(getattr(candidate, "value", candidate) or "").lower()
  2019. if name and name not in self._ACK_PLATFORM_UNRESOLVED:
  2020. return self._ACK_EMOJI_BY_PLATFORM.get(name, self._ACK_EMOJI_DEFAULT)
  2021. return self._ACK_EMOJI_DEFAULT
  2022. async def _react(
  2023. self,
  2024. chat_id: str,
  2025. message_id: str,
  2026. emoji: str,
  2027. *,
  2028. remove: bool = False,
  2029. ) -> bool:
  2030. """Egress one `react` op; best-effort (False on any failure, logged at debug)."""
  2031. if not chat_id or not message_id:
  2032. return False
  2033. result = await self._gated_op(
  2034. chat_id,
  2035. {
  2036. "op": "react",
  2037. "chat_id": chat_id,
  2038. "message_id": message_id,
  2039. "emoji": emoji,
  2040. "remove": remove,
  2041. "metadata": self._with_scope(chat_id, None),
  2042. },
  2043. decline_level=None,
  2044. )
  2045. return result is not None
  2046. async def on_processing_start(self, event) -> None:
  2047. """Add the in-progress reaction (op-gated; silent no-op otherwise)."""
  2048. message_id, chat_id = _event_ids(event)
  2049. if message_id and chat_id:
  2050. eyes, _ok, _fail = self._ack_emoji(event, chat_id)
  2051. await self._react(str(chat_id), str(message_id), eyes)
  2052. async def on_processing_complete(self, event, outcome) -> None:
  2053. """Swap the in-progress reaction for the outcome one (op-gated; silent
  2054. no-op otherwise)."""
  2055. message_id, chat_id = _event_ids(event)
  2056. if not (message_id and chat_id):
  2057. return
  2058. eyes, ok_emoji, fail_emoji = self._ack_emoji(event, chat_id)
  2059. await self._react(str(chat_id), str(message_id), eyes, remove=True)
  2060. if outcome == ProcessingOutcome.SUCCESS:
  2061. await self._react(str(chat_id), str(message_id), ok_emoji)
  2062. elif outcome == ProcessingOutcome.FAILURE:
  2063. await self._react(str(chat_id), str(message_id), fail_emoji)
  2064. # ── Phase 4 thread lifecycle ──────────────────────────────────────────
  2065. async def create_handoff_thread(
  2066. self,
  2067. parent_chat_id: str,
  2068. name: str,
  2069. ) -> Optional[str]:
  2070. """Create a thread/topic under ``parent_chat_id`` via the connector. One
  2071. `thread_create` op covers Discord (channel thread), Telegram (forum topic) and
  2072. Slack (named seed root message). None on any failure/unavailability so the
  2073. handoff watcher falls back to the parent."""
  2074. result = await self._gated_op(
  2075. str(parent_chat_id),
  2076. {
  2077. "op": "thread_create",
  2078. "chat_id": str(parent_chat_id),
  2079. "thread_name": (str(name or "").strip() or "handoff")[:100],
  2080. "metadata": self._with_scope(str(parent_chat_id), None),
  2081. },
  2082. decline_level=logging.INFO,
  2083. subject=parent_chat_id,
  2084. )
  2085. if result is None:
  2086. return None
  2087. thread_id = result.get("thread_id") or result.get("message_id")
  2088. return str(thread_id) if thread_id else None
  2089. async def rename_thread(
  2090. self,
  2091. thread_id: str,
  2092. name: str,
  2093. *,
  2094. only_if_current_name: Optional[str] = None,
  2095. prefer_connector_created: bool = False,
  2096. parent_chat_id: Optional[str] = None,
  2097. ) -> bool:
  2098. """Best-effort thread rename via the connector's `thread_rename` op. Prefer
  2099. ``prefer_connector_created=True``: the CONNECTOR enforces the no-clobber guard
  2100. from its own created-name memory, so the gateway need not reproduce the
  2101. initial name byte-for-byte (any normalization drift silently declined every
  2102. rename). ``only_if_current_name`` is the legacy string guard for older
  2103. connectors. ``parent_chat_id`` defaults to the thread id (Telegram needs the
  2104. containing chat; Discord ignores it)."""
  2105. cleaned = " ".join(str(name or "").split()).strip()
  2106. if not cleaned or not thread_id:
  2107. return False
  2108. chat_id = str(parent_chat_id or thread_id)
  2109. action: dict[str, Any] = {
  2110. "op": "thread_rename",
  2111. "chat_id": chat_id,
  2112. "message_id": str(thread_id),
  2113. "thread_name": cleaned[:100],
  2114. "metadata": self._with_scope(chat_id, None),
  2115. }
  2116. if prefer_connector_created:
  2117. action["only_if_connector_created"] = True
  2118. elif only_if_current_name is not None:
  2119. action["only_if_current_name"] = str(only_if_current_name)
  2120. result = await self._gated_op(
  2121. chat_id,
  2122. action,
  2123. decline_level=logging.INFO,
  2124. subject=thread_id,
  2125. platform=self._platform_by_chat.get(chat_id) or self._platform_by_chat.get(str(thread_id)),
  2126. )
  2127. return result is not None
  2128. # prompt kind -> resolver (order-independent: kinds are distinct keys).
  2129. _PROMPT_RESOLVERS = {
  2130. "exec_approval": RelayAdapter._resolve_exec_approval,
  2131. "slash_confirm": RelayAdapter._resolve_slash_confirm,
  2132. "clarify": RelayAdapter._resolve_clarify,
  2133. }