(Gj,dZddlmZddlZddlmZd7dZd8d Zd9d Zd:dZ d;dZ ddZd>dZd?d@dZdddddAd)ZdBd+Zdd,dCd1ZdBd2ZdDdEd6ZdS)FuRelay/connector support package for the Hermes gateway. EXPERIMENTAL. This package implements the gateway side of the "Gateway Gateway" relay design: a generic ``RelayAdapter`` plus the wire-serializable ``CapabilityDescriptor`` the connector hands it at handshake time, and the production ``WebSocketRelayTransport`` that dials the connector. The public API (module names, descriptor field set, transport protocol) MAY CHANGE without a deprecation cycle until at least two real Class-1 platforms (Discord + Telegram) have shaken out the schema. See ``docs/relay-connector-contract.md`` for the formal cross-repo interface. Activation is driven by configuration, not a separate feature flag: the relay platform is registered when a connector relay URL is configured (``GATEWAY_RELAY_URL`` env or ``gateway.relay_url`` in config.yaml). Deployments that don't set it are unaffected — exactly the same shape as ``gateway.proxy_url``. ) annotationsN)Optionalreturn Optional[str]ctjdd}|r|dS ddlm}|}|dpidd}|r|dSn#t$rYnwxYwdS) a%The connector relay endpoint URL, or None when relay is not configured. Checks ``GATEWAY_RELAY_URL`` (convenient for Docker) first, then ``gateway.relay_url`` in config.yaml. A non-empty value activates the relay platform; absence means a normal direct/single-tenant gateway. GATEWAY_RELAY_URL/r_load_gateway_configgateway relay_urlN)osenvirongetstriprstrip gateway.runr Exceptionurlr cfgs z-relay_platform_identities..Es-JJJq JJJJ,)relayr botId) rrrrsplit_relay_bot_ids_map isinstancedictstrappend) platforms_raw platformsidsoutplatformentrybot_ids rrelay_platform_identitiesr4/s*JNN#``), read from the per-platform entry in ``GATEWAY_RELAY_BOT_IDS``. None when absent (most platforms don't need one). username@N)r(rr)r*r+lstrip)r1r2r@s rrelay_bot_usernamerCesg  $ $X . .E%-99Z((  -x=='',, , 4r#tuple[str, str]c*tdS)u1The PRIMARY (platform, bot_id) — the first identity in the configured set. Kept for call sites that need a single representative identity (the default descriptor platform, the policy projection's primary). The full set is ``relay_platform_identities()``. Defaults to ``("relay", "")``. r)r4rr#rrelay_platform_identityrFrs % & &q ))r##tuple[Optional[str], Optional[str]]c4tjdd}tjdd}|r|s ddlm}|dpi}|p6t |ddpd}|p6t |ddpd}n#t$rYnwxYw|pd |pd fS) aThe (gateway_id, upgrade_secret) this gateway authenticates the WS upgrade with. Both come from enrollment (``hermes gateway enroll`` writes them to ``~/.hermes/.env``): ``GATEWAY_RELAY_ID`` identifies the enrolled instance, ``GATEWAY_RELAY_SECRET`` is the per-gateway signing secret. Either absent -> ``(None, None)`` and the transport dials unauthenticated (dev/test, or a connector that doesn't enforce auth). Checks env first (Docker), then ``gateway.relay_id`` / ``gateway.relay_secret`` in config.yaml. GATEWAY_RELAY_IDr GATEWAY_RELAY_SECRETrr r relay_id relay_secretNrrrrrr r+r) gateway_idsecretr rs rrelay_connection_authrP|s' 2B77==??J Z^^2B 7 7 = = ? ?F 6  8 8 8 8 8 8''))--i88>BC#Qs377:r+B+B+Hb'I'I'O'O'Q'QJMs377>2#>#>#D"EEKKMMFF    D   $$ //s*BD DDcxtjdd}|sp ddlm}|dpi}t |ddpd}n#t$rd}YnwxYw|dpdS) a The gateway's own PUBLIC inbound URL, asserted to the connector at provision. The connector delivers signed inbound POSTs to this URL and stores it on the tenant's route rows. It is gateway-asserted (the connector scopes it to the verified tenant, so a dishonest gateway can only misdirect its OWN inbound). The *source* of the value differs by deployment but the code path is uniform: a self-hosted operator sets ``GATEWAY_RELAY_ENDPOINT`` (mirrors how they set ``HERMES_DASHBOARD_PUBLIC_URL``); a hosted/NAS container has the same var stamped in (NAS knows the public URL only in that case). Absent -> the gateway provisions outbound-only (no inbound routes written). Env first (Docker), then ``gateway.relay_endpoint`` in config.yaml. GATEWAY_RELAY_ENDPOINTr rr r relay_endpointr N rrrrrr r+rrrs rrSrSs *..12 6 6 < < > >C   8 8 8 8 8 8''))--i88>BCcgg.339r::@@BBCC   CCC  ::c?? "d"AB B"!B" list[str]ctjdd}|s ddlm}|dpi}|dd}t |ttfr d|DSt|pd}n#t$rd}YnwxYwd| d DS) aDiscriminators (scope_ids / chat_ids / paths) this gateway's tenant owns. Gateway-provided config, paired with ``relay_endpoint()``: the connector writes one route row per (routeKey -> tenant, endpoint), so route keys only take effect alongside an endpoint. Empty -> outbound-only provisioning (the connector accepts an empty set and writes no route rows). ``GATEWAY_RELAY_ROUTE_KEYS`` is comma-separated; config.yaml ``gateway.relay_route_keys`` may be a list or a comma string. GATEWAY_RELAY_ROUTE_KEYSr rr r relay_route_keyscg|]D}t|#t|ESrr+rr ks rr"z$relay_route_keys..s9FFF1s1vv||~~FA FFFr#c^g|]*}||+Srrr\s rr"z$relay_route_keys..s- ; ; ;! ;AGGII ; ; ;r#r$) rrrrrr r)listtupler+rr')r=r rvals rrYrYs *..3R 8 8 > > @ @C    8 8 8 8 8 8''))--i88>BC'',b11C#e}-- GFFFFFFciR..&&((CC   CCC  ; ;syy~~ ; ; ;;sA"B=#B== C  C cRtjdd}|sp ddlm}|dpi}t |ddpd}n#t$rd}YnwxYw|pdS)u_Stable per-instance id this gateway forwards at provision (Phase 6 Unit α). Binds the connector's ``gatewayId -> instanceId`` so the connector can route inbound per-instance (not tenant-broadcast) once Phase 6 delivery lands. The value is the NAS ``AgentInstance.id`` for a managed agent (NAS stamps ``GATEWAY_RELAY_INSTANCE_ID`` into the container env, beside ``GATEWAY_RELAY_URL``); a self-hosted operator may set it explicitly. It is gateway-asserted but safely scoped: the org/tenant stays token-verified, so a dishonest gateway can only bind ITS OWN tenant's instance — the same posture as ``relay_endpoint()``. Absent -> the connector stores null and per-instance routing simply has no binding for this connection yet (back-compat). Env first (Docker/NAS), then ``gateway.relay_instance_id`` in config.yaml. GATEWAY_RELAY_INSTANCE_IDr rr r relay_instance_idNrMvaluer rs rrdrds JNN6 ; ; A A C CE   8 8 8 8 8 8''))--i88>BC 3R88>B??EEGGEE   EEE  =DrUcxtjdd}|sp ddlm}|dpi}t |ddpd}n#t$rd}YnwxYw|dpdS) ufThe gateway's WAKE URL, forwarded at provision (Phase 5 §5.2 wake PRIMITIVE). A poke target the connector issues a payload-free GET to when a buffered-only (going-idle) destination for this instance receives its first buffered event, so a suspended gateway wakes, reconnects its relay WS, and drains its delivery-leg backlog. The value's *source* differs by deployment but the code path is uniform: a managed/NAS container has ``GATEWAY_RELAY_WAKE_URL`` stamped in (NAS knows the Fly autostart / dashboard hostname); a self-hosted operator sets it explicitly (or passes ``--wake-url`` to ``hermes gateway enroll``). Gateway-asserted but safely scoped: the org/tenant stays token-verified, so a dishonest gateway can only register a wake target for ITS OWN instance — the same posture as ``relay_instance_id()`` / the retired ``relay_endpoint()``. Absent -> the connector stores null and simply can't wake this instance (buffering still works; the gateway drains whenever it next reconnects). Env first (Docker/NAS), then ``gateway.relay_wake_url`` in config.yaml. GATEWAY_RELAY_WAKE_URLr rr r relay_wake_urlr NrTres rriris& JNN3R 8 8 > > @ @E   8 8 8 8 8 8''))--i88>BC 0"55;<<BBDDEE   EEE  <<   $$rUrelay_dial_urlcN|d}|drd|tddz}n/|drd|tddz}|dr|dtd }|dS) uYMap the ``ws(s)://…/relay`` dial URL to the ``http(s)://…/relay/provision`` POST URL.r ws://http://Nwss://https:///relayz/relay/provisionr startswithlenendswithrjr=s r_provision_urlrvs    $ $C ~~g/#c'llmm,,  ! !/3s8}}~~.. ||H$"S]]N"# # # ##r#cN|d}|drd|tddz}n/|drd|tddz}|dr|dtd }|dS) uMap the ``ws(s)://…/relay`` dial URL to the ``http(s)://…/relay/policy`` POST URL. Same host derivation as ``_provision_url``; the connector mounts the relevance-policy update channel at ``/relay/policy`` (Phase 6 Unit ζ). r rlrmNrnrorpz /relay/policyrqrus r _policy_urlrxs    $ $C ~~g/#c'llmm,,  ! !/3s8}}~~.. ||H$"S]]N"#  r#Optional[dict]c|t\}}|r|dkrdSd}g} ddlm}|pi}||}t |t s?|dpidpi|}t |t s*|dpi|}t |t r|ni}d|vr|d}n*|d|d}|d}||d}t |t tfr d |D}nHt |tr3| rd | d D}n#t$rYnwxYwtj |d d  }|dv} |t!|nd} | s|s| sdS|| || dS)uProject a fronted platform's RELEVANCE config into the connector's generic vocabulary. The connector's relevance gate (Phase 6 Unit ζ) reasons over a platform-agnostic policy — ``requireAddress`` / ``freeResponseScopes`` / ``allowOtherBots`` — NOT over Discord/Telegram words. This is the gateway side of that contract: it reads the agent's existing relevance knobs and emits the generic shape the connector stores per-instance (Phase 1.5: the connector keys the policy by ``(tenant, platform, instanceId)``, so each fronted platform gets its own row — pass its name here). Mapping (the connector vocabulary ← the gateway's existing config): - ``requireAddress`` ← the platform's ``require_mention`` (the agent only engages a non-owner message that @mentions it / replies to it). - ``freeResponseScopes`` ← the platform's ``free_response_channels`` (the channel/scope ids where ``require_mention`` is waived — same scope vocabulary the connector's δ scope grants + ε floor use). - ``allowOtherBots`` ← ``{PLATFORM}_ALLOW_BOTS`` in {"mentions","all"} (whether bot-authored messages are admitted; default off). Read from the relay platform's config block (the platform the connector fronts, e.g. ``discord:``), falling back to the bridged top-level keys, then the ``{PLATFORM}_*`` env. ``platform`` defaults to the PRIMARY fronted platform (back-compat). Returns the generic dict, or None when relay isn't configured or the platform exposes no relevance knobs (⇒ the connector's quiet default already matches, so there's nothing to declare). Nr%rr r r.require_mentionfree_response_channelscg|]D}t|#t|ESrr[r cs rr"z*relay_relevance_policy..Vs9KKKCFFLLNNKSVV\\^^KKKr#c^g|]*}||+Srrr~s rr"z*relay_relevance_policy..Xs-LLL1!''))LQWWYYLLLr#r$ _ALLOW_BOTSr >allmentionsF)r1requireAddressfreeResponseScopesallowOtherBots)rFrr rr)r*r_r`r+rr'rrrupperlowerbool) r1_bot_idr{ free_responser rplat_cfgfrcallow_bots_envallow_other_botsrequire_addresss rrelay_relevance_policyrs6355' x7**tO!M 444444""$$*778$$(D)) Y++1r66{CCIrNNxXXH(D)) B ,,277AAH)(D99A88r  ( (&ll+<==OO WW& ' ' 3!gg&788Oll344 ;''233C cD%= ) ) MKKSKKKMM S ! ! Mciikk MLL #LLLM      Z^^x~~'7'7$D$D$DbIIOOQQWWYYN%)<</>/Jd?+++PUO =9It)+*   sF4G G%$G%g.@) instance_idwake_urltimeout provision_url access_tokenrNr3gateway_endpoint route_keysrrrfloatc ddl} ddl} ddl} ||||pd|d} |r|| d<|r|| d<| | d} | j|| dd |d d d  } | j|| 5}| | }dddn #1swxYwYn#| j j $r}d} | | pi dd}n#t$rYnwxYwtd|j|rd|ndz|d}~w| j j$r}td|j|d}~wwxYwt'|t(r| dstd|S)aPOST to the connector's ``/relay/provision`` and return the JSON body. The connector validates ``access_token`` against NAS, derives the authoritative tenant, mints the per-gateway secret + per-tenant delivery key, upserts the tenant's route rows, and returns ``{secret, deliveryKey, tenant, gatewayId, routeKeys}``. Raises RuntimeError with a user-facing message on any non-2xx / transport failure. rNr ) gatewayIdr1r&gatewayEndpoint routeKeys instanceIdwakeUrlutf-8POSTBearer application/json Authorizationz Content-TypeAcceptdatamethodheadersrerrorzconnector returned HTTP z: could not reach connector: rOz5connector returned an unexpected response (no secret))r8 urllib.errorurllib.requestdumpsencoderequestRequesturlopenr:readdecoder HTTPErrorrr RuntimeErrorcodeURLErrorreasonr)r*)rrrNr1r3rrrrrr8urllibbodyrreqresppayloadexcdetails r_post_provisionrps*KKK +1r D)(\#"Y ::d   " "7 + +D .  5|55.(  !  C P ^ # #C # 9 9 7Tjj!3!3!5!566G 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 < ! jj!2!2!4!455;@@"MMFF    D  1sx 1 1f5T]&]]]RT U    < PPPEEEFFCOP gt $ $TGKK,A,ATRSSS Nsm3C!:C C!CC!CC!!F$0E53AEE5 E E5E%E55F$FF$rc ddl}|d}t}|sdSt\}}|r|r|ddS ddlm}|}n.#t$r!}|d|Yd}~dSd}~wwxYwt}ddl } | } n#t$rd} YnwxYwtjd d pd | pd } t!} t#} t%}t'}g}i}|D]0\}} t)t+||| ||| | || }n.#t,$r!}|d ||Yd}~Sd}~wwxYw||dtjvstjdst1|dp| tjd <t1|dpdtjd<t1|dpdtjd<2|s5|ddd|DdSt1|dpd}|dtjd | |pdd|t5| | rdnd|pd|rdnddS)uzBoot-time relay self-provision: mint relay creds in-process, no human, no disk. Fires when relay is configured (``relay_url()`` set) and NO per-gateway secret is already present, AND the agent can resolve its own Nous access token. In that case the runtime resolves the agent's own Nous access token (the same ``resolve_nous_access_token()`` the enroll CLI / dashboard register use), POSTs ``/relay/provision`` asserting its own endpoint + route keys, and sets ``GATEWAY_RELAY_ID`` / ``GATEWAY_RELAY_SECRET`` / ``GATEWAY_RELAY_DELIVERY_KEY`` into ``os.environ`` so the subsequent ``register_relay_adapter()`` picks them up. The creds live ONLY in process memory — never written to ``~/.hermes/.env``. The trigger is deliberately NOT ``is_managed()``: that means "package-manager/NixOS-managed" and is False on a NAS-hosted Fly agent (which sets neither ``HERMES_MANAGED`` nor a ``.managed`` marker), so gating on it blocked the exact hosted case this is for. The real signal is "you pointed me at a connector and didn't pin a secret" — which is both NAS-independent and self-guarding: - A NAS-hosted agent: has ``GATEWAY_RELAY_URL``, no pinned secret, and a bootstrapped NAS token -> self-provisions. - A self-hosted operator who ran ``hermes gateway enroll``: has a PINNED ``GATEWAY_RELAY_SECRET`` -> skipped (the secret-present guard below). - A self-hosted box with a relay URL but no NAS identity: ``resolve_nous_access_token()`` fails -> graceful no-op. Stateless: process-env creds don't survive a restart, so a hosted container re-provisions every boot; the connector's rotation window covers a still- connected prior instance. An explicitly-pinned ``GATEWAY_RELAY_SECRET`` (env or config) is RESPECTED — self-provision skips so an operator pin isn't stomped. Returns True if it provisioned, False otherwise. NEVER raises: a provision failure logs and returns False so the gateway still boots (and ``register_relay_adapter`` will simply dial unauthenticated / be rejected, rather than the whole gateway crashing). rNr7Fz>relay self-provision skipped: GATEWAY_RELAY_SECRET already set)resolve_nous_access_tokenz?relay self-provision skipped: could not resolve Nous token (%s)r rIzgw-hermes) rrrNr1r3rrrrzJrelay self-provision failed for platform=%s (%s); continuing with the restrJrrO deliveryKeyGATEWAY_RELAY_DELIVERY_KEYzXrelay self-provision failed for ALL platforms (%s); gateway will boot without relay authr$c3 K|] \}}|V dSNr)r r!_s r z'self_provision_relay..0s&..41aQ......r#tenantzfrelay self-provisioned (gateway_id=%s tenant=%s platforms=%s routes=%d inbound=%s instance=%s wake=%s)?yesz outbound-onlyunboundnoneT)r9r;rrPinfohermes_cli.authrrr<r4socket gethostnamerrrrrSrYrdrirrvrr,r+joinrs)r9loggerdial_url existing_idexisting_secretrrr identitiesrhostrNendpointrrr provisionedresultr1r3rs rself_provision_relayrsJNNN    / /F{{H u$9#:#: K TUUUu======0022  XZ]^^^uuuuu  +,,JMMM!!##))++  2B77==??[C[IYQYC[C[JH!##J#%%KH KF&\\& $,X66)%!!)%'!   FF    NN\    HHHH   8$$$ " 3 32:>>J`;a;a 3-0K1H1H1VJ-W-WBJ) *14VZZ5I5I5OR1P1PBJ- .7:6::m;T;T;ZXZ7[7[BJ3 4  f HH..:... . .   u H%%+ , ,F KKp ):66 #  J. y%v    4sBA** B4BB+&C C! C!"%F F3F..F3r policy_urltokenpolicyintc ddl}ddl}ddl}||d}|j||dd|ddd} |j|| 5}t|j cdddS#1swxYwYdS#|j j $r} t| j cYd} ~ Sd} ~ w|j j $r} td | j| d} ~ wwxYw) uPOST the relevance policy to the connector's ``/relay/policy``; return the HTTP status. Authenticated with the gateway's own per-gateway upgrade token (the SAME bearer shape as the WS upgrade — ``make_upgrade_token``), so the connector resolves ``{tenant, instanceId}`` from its stored secret record, never the body. Raises RuntimeError on transport failure (the caller treats any failure as non-fatal — relevance is an optimization, not a boot dependency). rNrrrrrrrr)r8rrrrrrrrstatusrrrrrr) rrrrr8rrrrrs r _post_policyrBsKKK ::f   $ $W - -D .  .u...(  !  CP ^ # #C # 9 9 $Tt{## $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ < !38}} < PPPEEEFFCOPsNB%7B B%BB%B B%%C<4C C< C<C77C<c $ddl}|d}t}|sdSt\}}|r|sdS ddlm}|||}n.#t $r!}|d|Yd}~dSd}~wwxYwd}tD]\} } t| } |  tt||| } n.#t $r!}|d| |Yd}~^d}~wwxYw| d krwd }| d | d | d t| dpg| d|d| | |S)uEDeclare this gateway's relevance policy to the connector (Phase 6 Unit ζ). Runs at boot AFTER the per-gateway secret is resolved (self-provisioned or pinned), projecting the agent's relevance config into the generic vocabulary (``relay_relevance_policy``) and POSTing it to ``/relay/policy`` with the gateway's own upgrade token. The connector stores it per-instance and the relevance gate enforces it on delivery — so the SAME mention-gating / free-response / allow-bots behavior the agent applies directly also governs relay delivery, and excluded traffic never wakes a scaled-to-zero agent. Self-healing: the agent is the source of truth and re-declares every boot (mirrors the ``routeKeys`` upsert at provision). Idempotent — a full replace. NEVER raises and NEVER blocks boot: relevance is an optimization layered on the δ/ε authorization gate (which already protects isolation), so a failed declaration just means the connector keeps the prior/quiet policy. Returns True iff the connector accepted the policy (HTTP 200). rNr7F)make_upgrade_tokenzQrelay policy declaration failed to build token (%s); connector keeps prior policy)rrrz@relay policy declaration failed for platform=%s (%s); continuingTzSrelay policy declared (platform=%s require_address=%s free_scopes=%d allow_bots=%s)r1rrrz_relay policy declaration for platform=%s returned HTTP %s; connector keeps prior/default policy)r9r;rrPgateway.relay.authrrr<r4rrrxrrrs) r9rrrNrOrrr any_declaredr1rrrs rsend_relay_policyrcs&NNN    / /F{{H u.00J Vu999999"":v66 jlopppuuuuuL688''11 >  ![-B-B%X^___FF    NNRT\^a    HHHH   S==L KKe :&& +,,FJJ344:;; +,,      NNq     s0A B!A==B-C  C8C33C8Fforcerc  ||n t |s sdSddlm}m}ddlmddlmmt\  fd}| |dd |d d d dS)u;Register the generic ``relay`` platform via the platform registry. Registers when a relay URL is configured (or ``force=True`` for tests, which builds a transport-less adapter — the unit-test posture). Returns True if registration happened. Additive: uses the same registry path as plugin adapters, so no core dispatch changes are needed. When a URL is present the factory builds a live ``WebSocketRelayTransport``; the ``RelayAdapter`` negotiates the real ``CapabilityDescriptor`` at ``connect()`` time via ``transport.handshake()``. NFr) PlatformEntryplatform_registry) RelayAdapter)CONTRACT_VERSIONCapabilityDescriptorc  ddddddd }d} r5dd lm}t\}}| t||d }||| S) NRelayiFTplainchars) contract_versionr1labelmax_message_lengthsupports_draft_streaming supports_editsupports_threadsmarkdown_dialectlen_unitr)WebSocketRelayTransport)rrNupgrade_secret reconnect) transport)gateway.relay.ws_transportrrPr4) config placeholderrrrNrrrrr3r1 resolved_urls r_factoryz(register_relay_adapter.._factorys+*-#%*"$       J J J J J J)>)@)@ &J// 566%- !I$|FK9EEEEr#r%rcdS)NTrrr#rz(register_relay_adapter..sTr#builtinu🔌)nameradapter_factorycheck_fnsourceemojiT) rgateway.platform_registryrrgateway.relay.adapterrgateway.relay.descriptorrrrFregister) rrrrr rrrr3r1rs @@@@@@rregister_relay_adapterrs/33y{{L \uJJJJJJJJ222222OOOOOOOO.00Hf&F&F&F&F&F&F&F&F&F&FP $!\        4r#)rr)rr)rr*)r1r+rr)rrD)rrG)rrV)rjr+rr+r)r1rrry)rr+rr+rNr+r1r+r3r+rrrrVrrrrrrrr*)rr) rr+rr+rr*rrrr)FN)rrrrrr)__doc__ __future__rrtypingrrr4r(rCrFrPrSrYrdrirvrxrrrrrrrr#rrs$#""""" ,D(    ****00000####4<<<<46%%%%> $ $ $ $ ! ! ! ! OOOOOv"&"DDDDDDNHHHHVQUPPPPPPBMMMM`HHHHHHHr#