`gjoUdZddlmZddlZddlZddlmZmZmZm Z ddl m Z m Z ddl mZmZmZddlmZddlmZdd lmZej.eZdd Zeed Zd ed <GddeZy)uRelayAdapter — one generic gateway adapter fronted by the connector. EXPERIMENTAL. A single ``BasePlatformAdapter`` subclass that, at handshake, receives a ``CapabilityDescriptor`` from the connector telling it which platform it is fronting and which capabilities to advertise to the ``GatewayStreamConsumer``. It implements the four abstract methods (``connect`` / ``disconnect`` / ``send`` / ``get_chat_info``) plus the capability surface (``MAX_MESSAGE_LENGTH``, ``message_len_fn``, ``supports_draft_streaming``) by delegating wire I/O to an injected transport and reading capabilities off the descriptor. There is NO per-platform gateway code: the connector is the only side that knows "this chat_id maps to a Discord channel, send it via the Discord websocket." The gateway sees an ordinary ``MessageEvent`` in and calls ``adapter.send`` out. EXPERIMENTAL: the transport protocol and descriptor schema may change without a deprecation cycle until >=2 Class-1 platforms validate them. ) annotationsN)AnyCallableDictOptional)PlatformPlatformConfig)BasePlatformAdapter MessageEvent SendResult)CapabilityDescriptor)RelayTransport) SessionSourcec<t|jddzS)z1Count UTF-16 code units (Telegram's length unit).z utf-16-le)lenencode)texts H/root/.hermes/venv/lib/python3.12/site-packages/gateway/relay/adapter.py _utf16_lenr"s t{{;' (A --)charsutf16zDict[str, Callable[[str], int]]_LEN_FNSc(eZdZdZ d dfd ZeddZeddZ d ddZddddZ dd Z d d!d Z d"d Z dd Z dd Zd#dZd$dZd%dZdd&dZdZddZddZ d d'dZd(dZ d d)dZxZS)* RelayAdapterzLGeneric relay adapter advertising a connector-negotiated capability profile.ct||tj||_||_|j |_i|_i|_ i|_ |jdv|_ d|_ y)Nplain)super__init__rRELAY descriptor _transportmax_message_lengthMAX_MESSAGE_LENGTH_scope_by_chat_dm_user_by_chat_platform_by_chatmarkdown_dialectsupports_code_blocks_revocation_monitor)selfconfigr$ transport __class__s rr"zRelayAdapter.__init__1sq 0$#","?"?/1 1324$.$?$?}$T! BF rcy)aLRelay authorization is enforced by the connector, not locally. The connector authenticates this gateway's WS (per-instance secret) and performs owner-only author-binding resolution before delivering, so any inbound relay event was already authorized as THIS instance's bound user (``user_instance_binding``, keyed on the connector-observed author id). The instance therefore must not default-deny relay users for lack of a local ``RELAY_ALLOWED_USERS`` env allowlist. See ``BasePlatformAdapter.authorization_is_upstream``. Tr.s rauthorization_is_upstreamz&RelayAdapter.authorization_is_upstream\src^tj|jjtSN)rgetr$len_unitrr4s rmessage_len_fnzRelayAdapter.message_len_fnjs||DOO44c::rc.|jjSr7)r$supports_draft_streaming)r. chat_typemetadatas rr<z%RelayAdapter.supports_draft_streamingns 777rF) is_reconnectcK|j td|jj|jt |jdd}t |r||j t |jdd}t |r||j|jjd{}|sy |jjd{}|j|t|jdr|jy7b7>#t$r }tjd|Yd}~yd}~wwxYww)Nz(RelayAdapter has no transport configuredset_interrupt_inbound_handlerset_passthrough_handlerFzrelay handshake failed: %s auth_revokedT)r% RuntimeErrorset_inbound_handler _on_inboundgetattrcallable on_interrupt_on_passthroughconnect handshake Exceptionloggerwarning_apply_descriptorhasattr_start_revocation_monitor)r.r? set_interruptset_passthroughokr$excs rrKzRelayAdapter.connectvs$ ?? "IJ J ++D,<,<= 1PRVW M " $++ , "$//3LdS O $ D00 1??**, , #88::J z* 4??N 3  * * ,+-;  NN7 = sNCED'E D+*D)+D+/9E)D++ E4E EEEc|j|jjsy tj|j d|_y#t $r d|_YywxYw)zSpawn (once) the task that turns a transport auth-revocation into a clean non-retryable 'relay disabled' fatal. Idempotent.Nzrelay-revocation-monitor)name)r-doneasyncio create_task_watch_for_revocationrDr4s rrRz&RelayAdapter._start_revocation_monitorsf  # # /8P8P8U8U8W  ,'.':':**,3M(D $ ,(,D $ ,s*AA'&A'cK|j} | t|ddrntj|d{. | t|ddsyt j d|jddd |jd{y7Y#tj$rwxYw7#t$rt jd d YywxYww) aPoll the transport for a terminal 4401 revocation (opt-out). On revocation, surface a non-retryable `relay_disabled` fatal so the dashboard renders a clean 'Relay disabled' state instead of a red 'retrying' spin, and notify the gateway's fatal-error handler so the adapter is cleanly removed (it is NOT queued for reconnection, because the credential is dead until the instance is recreated).TNrCFuIrelay credential revoked (opt-out) — marking the relay adapter disabledrelay_disableduARelay disabled (opted out — recreate the instance to re-enable)) retryablez*relay revocation fatal-error notify failedexc_info) r%rGrZsleepCancelledErrorrNrO_set_fatal_error_notify_fatal_errorrMdebug)r.poll_interval_sr0s rr\z"RelayAdapter._watch_for_revocationsOO  $ >5(QmmO444  GI~u$M  W   O   V**, , ,!5%%    - V LLEPTL U Vsa C)BBB:C:B/ B-B/CBB**C-B// CCCCcZ||_|j|_|jdv|_y)zCAdopt a (re)negotiated descriptor into the live capability surface.rN)r$r&r'r+r,)r.r$s rrPzRelayAdapter._apply_descriptors*$","?"?$.$?$?}$T!rcdK|j||j|d{y7w)zGBridge a connector-delivered MessageEvent into the normal adapter path.N)_capture_scopehandle_message)r.events rrFzRelayAdapter._on_inbounds( E"!!%(((s &0.0c t|dd}|syt|dd}|syt|dd}t|d|}|r&|dk7r!t||jt|<t|dd}|r"t||jt|<yt|dd}|r"t||jt|<yy#t $rYywxYw) uRemember a chat_id's egress discriminator from an inbound event so our outbound (the agent's reply) can re-assert it for the connector's egress tenant resolution. Never raises — scope tracking must not break inbound. Two cases, matching the connector's two tenant-resolution paths: - SCOPED message: remember chat_id -> scope_id. The connector resolves the tenant from metadata.scope_id (routing table). - DM (no scope): remember chat_id -> the authentic author user_id. A DM carries no scope discriminator, so the connector instead resolves the tenant from the recipient's author binding (resolveByUser); it needs the user_id on the OUTBOUND action to do that. Without this, a DM reply has no resolvable discriminator and the connector's egress guard declines it as "target not routed to an onboarded tenant". See gateway-gateway routedEgressGuard.ts / the tenant resolvers. sourceNchat_idplatformvaluerelayscope_iduser_id)rGstrr*r(r)rM)r.rlsrcchatrpplatform_valuescoperts rrjzRelayAdapter._capture_scopes  %40C3 40DsJ5H$XwAN.G";474G&&s4y1CT2E14U##CI.c9d3G36w<%%c$i0   s"CCA2C0C CCc6t|xsi}|jds+|jjt|}|r||d<|jds<|jds+|jjt|}|r||d<|S)uEnsure the outbound metadata carries the discriminator the connector's egress guard needs to resolve the owning tenant. Two cases: - SCOPED reply: re-attach metadata.scope_id (routing-table resolution). - DM reply: there is no scope, so re-attach metadata.user_id — the authentic author id we saw inbound — which the connector resolves to the tenant via the recipient's author binding (resolveByUser). Without one of these, egress is declined as 'target not routed to an onboarded tenant'. See gateway-gateway routedEgressGuard.ts / the tenant resolvers. No-op when the relevant value is already present or unknown for this chat. rsrt)dictr8r(rur))r.ror>metarydm_users r _with_scopezRelayAdapter._with_scopes $HN3xx #''++CL9E#(Z xx #DHHY,?++//G =G")Y rc`t|jdd}|sytfd|DS)aWhether ``platform`` is one of the platforms this gateway fronts over the relay (Phase 1.5). Reads the transport's advertised identity set; used to decide whether a follow-up's platform-prefixed `kind` names a real fronted platform worth tagging on the frame (vs. leaving egress to the session default). Safe when the transport is absent or single-identity. _identitiesNFc3.K|] \}}|k(ywr7r3).0p_rps r z4RelayAdapter._platform_is_fronted..:s1TQ1=1s)rGr%any)r.rpidss ` r_platform_is_frontedz!RelayAdapter._platform_is_fronted1s. doo}d;1S111rcDK|j||d{y7w)aBridge a connector-delivered /stop into the adapter's interrupt path. The connector forwards a mid-turn interrupt down the socket owned by the gateway instance running ``session_key``; this routes it to the existing per-session interrupt mechanism (sets the ``_active_sessions[session_key]`` Event and clears typing), cancelling the right turn without touching sibling sessions. N)interrupt_session_activity)r. session_keyros rrIzRelayAdapter.on_interrupt<s--k7CCCs   c bK t|ddxsd}|dk(r>|j|}|+|j||j|d{ytj d|t|ddt|ddy74#t $rtjd d YywxYww) uLHandle a connector-forwarded passthrough request (Phase 5 §5.1). The passthrough plane (Discord interactions, Twilio webhooks, …) answers the provider's latency-critical ACK at the connector EDGE, then forwards the real, ALREADY-SANITIZED request to this gateway over the outbound WS. The connector is the trust boundary: it verified the provider signature at the edge and stripped any shared-identity credential (e.g. a Discord interaction follow-up token) into its vault — so this body carries no token, and the agent later acts on it via the token-less ``follow_up`` path (``send_follow_up``), never holding the credential. For a Discord interaction we decode the (JSON) body and convert it to a normalized ``MessageEvent`` so it flows through the SAME agent path as a chat message (``handle_message``); the agent's reply egresses over the normal outbound/follow_up path. Non-JSON or non-interaction forwards are logged and dropped for now (Twilio/SMS over the relay is a later unit). NEVER raises: a malformed forward must not kill the read loop. NOTE (open semantic sub-design, flagged for review): the interaction -> MessageEvent mapping below is the v1 default. The exact agent UX for a slash-command / button interaction (vs. a plain message) — command name surfacing, option rendering, deferred-vs-immediate response — is the open piece tracked in the spec; the TRANSPORT + receive mechanism (this whole path) is settled. rprdiscordNzMrelay passthrough_forward dropped (no handler): platform=%s method=%s path=%smethod?pathz)relay passthrough_forward handling failedTr`)rG_discord_interaction_to_eventrjrkrNinforMrO)r.forward buffer_idrprls rrJzRelayAdapter._on_passthroughGs6 Ww B7=2H9$::7C$''.--e444 KK_3/-  5 W NNFQUN V WsGB/AB BB B/.B B/B B,)B/+B,,B/c pddl}ddlm} |jt t |ddj d}t|tsy|jd}|jdxsi}|d k(rt|jd xsd }n&|d k(rt|jd xsd }nd }|jdxsi}t|tr|jdndxs|jdxsi} t|jdxsd } |jd} ttj| | rdndt| tr+| jdrt| jdndt| tr+| jdrt| jdnd| r t| nd|jdrt|jdnd} t||j | S#t$rYywxYw)aConvert a forwarded Discord interaction body to a MessageEvent, or None. Builds the session source the same way the connector does for an interaction (``interactionSessionSource`` on the connector side), so the agent's session key matches the one the connector bound the follow-up capability under. Returns None when the body isn't a usable interaction (e.g. a PING, which the connector already answers at the edge and never forwards). rN) MessageTypebodyrzutf-8typedatarrXr custom_idmemberuser channel_idguild_idchanneldmidusername)rpror=rt user_namers message_id)r message_typern)jsongateway.platforms.baserloadsbytesrGdecoderM isinstancer{r8rurrr#r TEXT) r.rrrpayloadityperrrrrrrns rrz*RelayAdapter._discord_interaction_to_eventss 6 jjww'D!E!L!LW!UVG'4( F#{{6"(b A:txx'-2.D aZtxx ,23DDX&,"&0&> 6"DfW[[Y_M`fdf\28b9 ;;z*^^#+i+5dD+AdhhtnC'Z^3=dD3IdhhWaNbc$((:./hl&.S]D18T1Bs7;;t,- K4D4DVTT7  s4H)) H54H5cK|j6|jj |jd{d|_|j lt |j dd}t|r' |}tj|r |d{|j jd{yy7#tjtf$rYwxYw7I#t$rtjddYiwxYw7Ow)Ngo_idlez$relay going_idle failed during drainTr`) r-cancelrZrcrMr%rGrH iscoroutinerNrf disconnect)r.rresults rrzRelayAdapter.disconnects  # # /  $ $ + + - ....(,D $ ?? &dooy$?G X"))F**62$ //,,. . .' ' /**I6  &% XLL!GRVLWX .sy'D CB>C5D 4!C!CC!D 7D8D >CCD CD C!! DD DD c0K|jyt|jdd}t|sy |}tj|rt |d{St |S7#t $rtjddYywxYww)uQuiesce the relay for a scale-to-zero suspend (D12 / Phase 0). Unlike ``disconnect()`` (terminal teardown for shutdown/restart), this keeps the adapter's reconnect path armed so the gateway re-dials and drains its buffered backlog when the machine wakes. Delegates to the transport's ``go_dormant()`` when available; a transport without it (the stub) is a no-op that returns False, so callers degrade safely. NOTE: deliberately does NOT stop the revocation monitor — going dormant is not a teardown; the monitor stays live so a real opt-out/revocation during dormancy is still surfaced on wake. NF go_dormantzrelay go_dormant failedTr`) r%rGrHrZrboolrMrNrf)r.rrs rrzRelayAdapter.go_dormants ?? "T__lDA  # $,F""6*&L))< )  LL2TL B sF1B&A0A.A0"B# A0-B.A00 BBBBc K|j tddS|jjd||||j||d|jj t |d{}tt|j d|j d|j d  S7Hw) NF no transportsuccesserrorsend)oprocontentreply_tor>rprrrrrr)r%r send_outboundr~r*r8rur)r.rorrr>rs rrzRelayAdapter.sends ?? "e>B B44""$ ,,Wh?  ++//G =5   I./zz,/**W%    sA2B?4B=5A B?cvK|j|ddS|jj|d{S7w)Nr)rXr)r% get_chat_info)r.ros rrzRelayAdapter.get_chat_infos6 ?? "#T2 2__227;;;;s 0979cK|j tddSd}|r,d|vr(|jddd}|j|r|}|jj d||||xsid | d{}tt |j d |j d |j d S7Hw)aSend via a shared-identity capability bound to a session (A2 outbound). The gateway never holds the credential: it names the session it is already in plus the capability ``kind``, and the connector resolves the real value from its vault and egresses (enforcing the tenant match). Used e.g. to post a Discord interaction follow-up as the shared bot without the token ever reaching the gateway. See RelayTransport.send_follow_up. NFrr.r follow_up)rrkindrr>rrrrr)r%r splitrsend_follow_uprr8)r.rrrr>follow_up_platformprefixrs rrzRelayAdapter.send_follow_ups ?? "e>B B " C4KZZQ'*F((0%+"55!*"$N  (6   I./zz,/**W%    sA4C6B?7A Cr7)r/r r$r r0zOptional[RelayTransport]returnNone)rr)rzCallable[[str], int])NN)r= Optional[str]r>Optional[Dict[str, Any]]rr)r?rrr)rr)g?)rgfloatrr)r$r rr)rorur>rrDict[str, Any])rprurr)rrurorurr)rrrr) rorurrurrr>rrr )rorurr) rrurrurrur>rrr )__name__ __module__ __qualname____doc__r"propertyr5r:r<rKrRr\rPrFrjr~rrIrJrrrrrr __classcell__)r1s@rrr.sYV /3 (F(F)(F, (F  (FV  ;; $(-18 8+8  85:7r ,V@U ) ,\6 2 D*WX+UZ/>>#'-1      +    2<.2 ) ) )  ) + )  ) rr)rrurint)r __future__rrZloggingtypingrrrrgateway.configrr rr r r gateway.relay.descriptorr gateway.relay.transportrgateway.sessionr getLoggerrrNrrr__annotations__rr3rrrsj$#003PP92)   8 $. - ) t &t r