@clawpump/claw-agent 0.1.4 → 0.1.6

package/agent/gateway/platforms/yuanbao_proto.py

@@ -492,6 +492,29 @@ def decode_biz_msg(data: bytes) -> dict:
 #   field 10: url (string)
 #   field 11: file_size (uint32)
 #   field 12: file_name (string)
+#   field 999: ext_map (map<string, string>)  ← extension info for WeChat chat-history forwarding
+#       protobuf map is wire-encoded as a repeated message entry; each entry has:
+#         field 1: key (string)
+#         field 2: value (string)
+#       key format: wexin_forward_msg_[forward_msg_id]_[userid]
+#       value: base64(ForwardMsgData protobuf)  ← NOT JSON; it is base64-encoded
+#              protobuf bytes that must be parsed with decode_forward_msg_data().
+
+
+def _encode_map_entry(key: str, value: str) -> bytes:
+    """Encode a single entry of a protobuf map<string, string> (field 1 key, field 2 value)."""
+    buf = b""
+    if key:
+        buf += _encode_field(1, WT_LEN, _encode_string(str(key)))
+    if value:
+        buf += _encode_field(2, WT_LEN, _encode_string(str(value)))
+    return buf
+
+
+def _decode_map_entry(data: bytes) -> tuple[str, str]:
+    """Decode a single entry of a protobuf map<string, string>, returning (key, value)."""
+    fdict = _fields_to_dict(_parse_fields(data))
+    return _get_string(fdict, 1), _get_string(fdict, 2)
 
 
 def _encode_msg_content(content: dict) -> bytes:
@@ -518,6 +541,12 @@ def _encode_msg_content(content: dict) -> bytes:
         if url:
             img_buf += _encode_field(5, WT_LEN, _encode_string(url))
         buf += _encode_field(8, WT_LEN, _encode_message(img_buf))
+    # ext_map (map<string, string>, field 999) — repeated message entries
+    ext_map = content.get("ext_map")
+    if isinstance(ext_map, dict):
+        for k, v in ext_map.items():
+            entry_bytes = _encode_map_entry(str(k), str(v))
+            buf += _encode_field(999, WT_LEN, _encode_message(entry_bytes))
     return buf
 
 
@@ -550,6 +579,14 @@ def _decode_msg_content(data: bytes) -> dict:
             imgs.append(img)
     if imgs:
         content["image_info_array"] = imgs
+    # ext_map (field 999) — decode repeated map entries into a plain dict
+    ext_map: dict[str, str] = {}
+    for entry_bytes in _get_repeated_bytes(fdict, 999):
+        k, v = _decode_map_entry(entry_bytes)
+        if k:
+            ext_map[k] = v
+    if ext_map:
+        content["ext_map"] = ext_map
     return content
 
 
@@ -710,9 +747,178 @@ def decode_inbound_push(data: bytes) -> Optional[dict]:
 
 
 # ============================================================
-# 出站消息编码
+# WeChat forwarded chat-history parsing (ForwardMsgData)
 # ============================================================
+#
+# The value of ext_map["wexin_forward_msg_<id>_<userid>"] is a base64-encoded
+# ForwardMsgData protobuf (NOT JSON). Structure (verified against live captures):
+#
+#   message ForwardMsgData {
+#     uint32 sub_type   = 1;   // 1 = WeChat chat-history forward
+#     uint32 begin_time = 2;
+#     uint32 end_time   = 3;
+#     string nick_name  = 4;   // forwarder's WeChat nickname
+#     repeated ForwardMsg msg = 5;
+#   }
+#   message ForwardMsg {
+#     string sender    = 1;
+#     uint32 time      = 2;
+#     string plainText = 3;
+#     repeated MsgContent msgContent = 4;
+#   }
+#   message MsgContent {
+#     uint32 type = 1;                  // 1=TEXT, 2=MULTIMEDIA, 3=nested forward
+#     string text = 2;                  // type==1
+#     repeated Multimedia multimedia = 3;  // type==2
+#   }
+#   message Multimedia {
+#     string type      = 1;   // image / file / document / url / video
+#     string url       = 2;
+#     string file_name = 4;
+#     uint32 file_size = 5;
+#     uint32 width     = 6;
+#     uint32 height    = 7;
+#     string media_id  = 15;  // can be used directly as a ybres RID
+#     string res_type  = 24;
+#   }
+
+
+def _decode_forward_multimedia(data: bytes) -> dict:
+    """Decode a single Multimedia sub-message into the dict shape expected by _format_multimedia."""
+    fdict = _fields_to_dict(_parse_fields(data))
+    media: dict = {}
+    mtype = _get_string(fdict, 1)
+    if mtype:
+        media["type"] = mtype
+    url = _get_string(fdict, 2)
+    if url:
+        media["url"] = url
+    file_name = _get_string(fdict, 4)
+    if file_name:
+        media["file_name"] = file_name
+    file_size = _get_varint(fdict, 5)
+    if file_size:
+        media["file_size"] = file_size
+    media_id = _get_string(fdict, 15)
+    if media_id:
+        media["media_id"] = media_id
+    return media
+
+
+def _decode_forward_msg_content(data: bytes) -> dict:
+    """Decode a single MsgContent sub-message into {type, text?, multimedia?}."""
+    fdict = _fields_to_dict(_parse_fields(data))
+    content: dict = {"type": _get_varint(fdict, 1)}
+    text = _get_string(fdict, 2)
+    if text:
+        content["text"] = text
+    multimedia = [
+        _decode_forward_multimedia(b) for b in _get_repeated_bytes(fdict, 3)
+    ]
+    if multimedia:
+        content["multimedia"] = multimedia
+    return content
+
+
+def _decode_forward_msg(data: bytes) -> dict:
+    """Decode a single ForwardMsg sub-message into {sender, plainText, msgContent}."""
+    fdict = _fields_to_dict(_parse_fields(data))
+    return {
+        "sender": _get_string(fdict, 1),
+        "time": _get_varint(fdict, 2),
+        "plainText": _get_string(fdict, 3),
+        "msgContent": [
+            _decode_forward_msg_content(b) for b in _get_repeated_bytes(fdict, 4)
+        ],
+    }
+
+
+def decode_forward_msg_data(data: bytes) -> Optional[dict]:
+    """Parse ForwardMsgData protobuf bytes (the base64-decoded ext_map value).
+
+    Args:
+        data: ForwardMsgData protobuf bytes, after base64 decoding.
+
+    Returns:
+        A dict matching the structure consumed by
+        ``ForwardedRecordsParseMiddleware.build_forward_text``
+        (``sub_type`` / ``nick_name`` / ``msg`` list); ``None`` on parse failure.
+    """
+    try:
+        fdict = _fields_to_dict(_parse_fields(data))
+        return {
+            "sub_type": _get_varint(fdict, 1),
+            "begin_time": _get_varint(fdict, 2),
+            "end_time": _get_varint(fdict, 3),
+            "nick_name": _get_string(fdict, 4),
+            "msg": [_decode_forward_msg(b) for b in _get_repeated_bytes(fdict, 5)],
+        }
+    except Exception as e:
+        if DEBUG_MODE:
+            logger.debug("[yuanbao_proto] decode_forward_msg_data failed: %s", e)
+        return None
+
+
+def _encode_forward_multimedia(media: dict) -> bytes:
+    buf = b""
+    for fn, key in [(1, "type"), (2, "url"), (4, "file_name"), (15, "media_id")]:
+        v = media.get(key, "")
+        if v:
+            buf += _encode_field(fn, WT_LEN, _encode_string(str(v)))
+    for fn, key in [(5, "file_size"), (6, "width"), (7, "height")]:
+        v = media.get(key, 0)
+        if v:
+            buf += _encode_field(fn, WT_VARINT, _encode_varint(int(v)))
+    return buf
 
+
+def _encode_forward_msg_content(content: dict) -> bytes:
+    buf = _encode_field(1, WT_VARINT, _encode_varint(int(content.get("type", 0))))
+    text = content.get("text", "")
+    if text:
+        buf += _encode_field(2, WT_LEN, _encode_string(str(text)))
+    for media in content.get("multimedia") or []:
+        buf += _encode_field(3, WT_LEN, _encode_message(_encode_forward_multimedia(media)))
+    return buf
+
+
+def _encode_forward_msg(msg: dict) -> bytes:
+    buf = b""
+    sender = msg.get("sender", "")
+    if sender:
+        buf += _encode_field(1, WT_LEN, _encode_string(str(sender)))
+    time_val = msg.get("time", 0)
+    if time_val:
+        buf += _encode_field(2, WT_VARINT, _encode_varint(int(time_val)))
+    plain = msg.get("plainText", "")
+    if plain:
+        buf += _encode_field(3, WT_LEN, _encode_string(str(plain)))
+    for mc in msg.get("msgContent") or []:
+        buf += _encode_field(4, WT_LEN, _encode_message(_encode_forward_msg_content(mc)))
+    return buf
+
+
+def encode_forward_msg_data(data: dict) -> bytes:
+    """Encode ForwardMsgData protobuf bytes (inverse of ``decode_forward_msg_data``).
+
+    Mainly used to build mock / test data; production code never needs to encode this.
+    """
+    buf = _encode_field(1, WT_VARINT, _encode_varint(int(data.get("sub_type", 0))))
+    for fn, key in [(2, "begin_time"), (3, "end_time")]:
+        v = data.get(key, 0)
+        if v:
+            buf += _encode_field(fn, WT_VARINT, _encode_varint(int(v)))
+    nick = data.get("nick_name", "")
+    if nick:
+        buf += _encode_field(4, WT_LEN, _encode_string(str(nick)))
+    for msg in data.get("msg") or []:
+        buf += _encode_field(5, WT_LEN, _encode_message(_encode_forward_msg(msg)))
+    return buf
+
+
+# ============================================================
+# Outbound message encoding
+# ============================================================
 def _encode_send_c2c_req(
     to_account: str,
     from_account: str,
@@ -724,7 +930,7 @@ def _encode_send_c2c_req(
     trace_id: str = "",
 ) -> bytes:
     """
-    编码 SendC2CMessageReq biz payload。
+    Encode a SendC2CMessageReq biz payload.
 
     SendC2CMessageReq fields:
       1: msg_id (string)
@@ -769,7 +975,7 @@ def _encode_send_group_req(
     trace_id: str = "",
 ) -> bytes:
     """
-    编码 SendGroupMessageReq biz payload。
+    Encode a SendGroupMessageReq biz payload.
 
     SendGroupMessageReq fields:
       1: msg_id (string)
@@ -816,18 +1022,20 @@ def encode_send_c2c_message(
     trace_id: str = "",
 ) -> bytes:
     """
-    编码 C2C 发消息请求，返回完整 ConnMsg bytes（可直接发送到 WebSocket）。
+    Encode a C2C send-message request and return the full ConnMsg bytes
+    (ready to be sent over WebSocket).
 
     Args:
-        to_account:   收件人账号
-        msg_body:     消息体列表，每个元素: {"msg_type": str, "msg_content": dict}
-                      例如: [{"msg_type": "TIMTextElem", "msg_content": {"text": "hello"}}]
-        from_account: 发件人账号（机器人账号）
-        msg_id:       消息唯一 ID（空时使用 req_id）
-        msg_random:   随机数（防重）
-        msg_seq:      消息序列号（可选）
-        group_code:   来自群聊的私聊场景时填写
-        trace_id:     链路追踪 ID
+        to_account:   recipient account
+        msg_body:     list of message-body elements; each item is
+                      {"msg_type": str, "msg_content": dict}.
+                      Example: [{"msg_type": "TIMTextElem", "msg_content": {"text": "hello"}}]
+        from_account: sender account (the bot account)
+        msg_id:       unique message ID (req_id is used when empty)
+        msg_random:   random number for de-duplication
+        msg_seq:      message sequence number (optional)
+        group_code:   filled in for the "private chat originating from a group" case
+        trace_id:     trace ID for request tracing
 
     Returns:
         ConnMsg bytes
@@ -866,18 +1074,19 @@ def encode_send_group_message(
     trace_id: str = "",
 ) -> bytes:
     """
-    编码群消息发送请求，返回完整 ConnMsg bytes（可直接发送到 WebSocket）。
+    Encode a group send-message request and return the full ConnMsg bytes
+    (ready to be sent over WebSocket).
 
     Args:
-        group_code:   群号
-        msg_body:     消息体列表
-        from_account: 发件人账号（机器人账号）
-        msg_id:       消息唯一 ID
-        to_account:   指定接收者（一般为空）
-        random:       去重随机字符串
-        msg_seq:      消息序列号
-        ref_msg_id:   引用消息 ID
-        trace_id:     链路追踪 ID
+        group_code:   group ID
+        msg_body:     list of message-body elements
+        from_account: sender account (the bot account)
+        msg_id:       unique message ID
+        to_account:   targeted recipient (usually empty)
+        random:       random string for de-duplication
+        msg_seq:      message sequence number
+        ref_msg_id:   ID of the referenced (quoted) message
+        trace_id:     trace ID for request tracing
 
     Returns:
         ConnMsg bytes

package/agent/gateway/relay/__init__.py

@@ -0,0 +1,375 @@
+"""Relay/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``.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+
+def relay_url() -> Optional[str]:
+    """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.
+    """
+    url = os.environ.get("GATEWAY_RELAY_URL", "").strip()
+    if url:
+        return url.rstrip("/")
+    try:
+        from gateway.run import _load_gateway_config  # late import to avoid cycle
+
+        cfg = _load_gateway_config()
+        url = (cfg.get("gateway") or {}).get("relay_url", "").strip()
+        if url:
+            return url.rstrip("/")
+    except Exception:  # noqa: BLE001 - config absence/parse must never crash registration
+        pass
+    return None
+
+
+def relay_platform_identity() -> tuple[str, str]:
+    """Platform + bot id this gateway fronts over the relay (for the handshake hello).
+
+    Defaults to ``("relay", "")``; overridable via ``GATEWAY_RELAY_PLATFORM`` /
+    ``GATEWAY_RELAY_BOT_ID`` so one connector can front several platforms.
+    """
+    platform = os.environ.get("GATEWAY_RELAY_PLATFORM", "relay").strip() or "relay"
+    bot_id = os.environ.get("GATEWAY_RELAY_BOT_ID", "").strip()
+    return platform, bot_id
+
+
+def relay_connection_auth() -> tuple[Optional[str], Optional[str]]:
+    """The (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_id = os.environ.get("GATEWAY_RELAY_ID", "").strip()
+    secret = os.environ.get("GATEWAY_RELAY_SECRET", "").strip()
+    if not (gateway_id and secret):
+        try:
+            from gateway.run import _load_gateway_config  # late import to avoid cycle
+
+            cfg = (_load_gateway_config().get("gateway") or {})
+            gateway_id = gateway_id or str(cfg.get("relay_id", "") or "").strip()
+            secret = secret or str(cfg.get("relay_secret", "") or "").strip()
+        except Exception:  # noqa: BLE001 - config absence/parse must never crash registration
+            pass
+    return (gateway_id or None, secret or None)
+
+
+def relay_endpoint() -> Optional[str]:
+    """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.
+    """
+    url = os.environ.get("GATEWAY_RELAY_ENDPOINT", "").strip()
+    if not url:
+        try:
+            from gateway.run import _load_gateway_config  # late import to avoid cycle
+
+            cfg = (_load_gateway_config().get("gateway") or {})
+            url = str(cfg.get("relay_endpoint", "") or "").strip()
+        except Exception:  # noqa: BLE001 - config absence/parse must never crash boot
+            url = ""
+    return url.rstrip("/") or None
+
+
+def relay_route_keys() -> list[str]:
+    """Discriminators (guild_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.
+    """
+    raw = os.environ.get("GATEWAY_RELAY_ROUTE_KEYS", "").strip()
+    if not raw:
+        try:
+            from gateway.run import _load_gateway_config  # late import to avoid cycle
+
+            cfg = (_load_gateway_config().get("gateway") or {})
+            val = cfg.get("relay_route_keys", "")
+            if isinstance(val, (list, tuple)):
+                return [str(k).strip() for k in val if str(k).strip()]
+            raw = str(val or "").strip()
+        except Exception:  # noqa: BLE001
+            raw = ""
+    return [k.strip() for k in raw.split(",") if k.strip()]
+
+
+def _provision_url(relay_dial_url: str) -> str:
+    """Map the ``ws(s)://…/relay`` dial URL to the ``http(s)://…/relay/provision`` POST URL."""
+    raw = relay_dial_url.rstrip("/")
+    if raw.startswith("ws://"):
+        raw = "http://" + raw[len("ws://"):]
+    elif raw.startswith("wss://"):
+        raw = "https://" + raw[len("wss://"):]
+    if raw.endswith("/relay"):
+        raw = raw[: -len("/relay")]
+    return f"{raw}/relay/provision"
+
+
+def _post_provision(
+    *,
+    provision_url: str,
+    access_token: str,
+    gateway_id: str,
+    platform: str,
+    bot_id: str,
+    gateway_endpoint: Optional[str],
+    route_keys: list[str],
+    timeout: float = 15.0,
+) -> dict:
+    """POST 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.
+    """
+    import json
+    import urllib.error
+    import urllib.request
+
+    body: dict = {
+        "gatewayId": gateway_id,
+        "platform": platform,
+        "botId": bot_id,
+        "gatewayEndpoint": gateway_endpoint or "",
+        "routeKeys": route_keys,
+    }
+    data = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(
+        provision_url,
+        data=data,
+        method="POST",
+        headers={
+            "Authorization": f"Bearer {access_token}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            payload = json.loads(resp.read().decode())
+    except urllib.error.HTTPError as exc:
+        detail = ""
+        try:
+            detail = (json.loads(exc.read().decode()) or {}).get("error", "")
+        except Exception:
+            pass
+        raise RuntimeError(
+            f"connector returned HTTP {exc.code}" + (f": {detail}" if detail else "")
+        ) from exc
+    except urllib.error.URLError as exc:
+        raise RuntimeError(f"could not reach connector: {exc.reason}") from exc
+
+    if not isinstance(payload, dict) or not payload.get("secret"):
+        raise RuntimeError("connector returned an unexpected response (no secret)")
+    return payload
+
+
+def self_provision_relay() -> bool:
+    """Boot-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).
+    """
+    import logging
+
+    logger = logging.getLogger("gateway.relay")
+
+    dial_url = relay_url()
+    if not dial_url:
+        return False
+
+    # Respect an already-present (pinned/stamped) secret — don't stomp it. This
+    # is also what makes a self-hosted, enrolled gateway skip self-provision.
+    existing_id, existing_secret = relay_connection_auth()
+    if existing_id and existing_secret:
+        logger.info("relay self-provision skipped: GATEWAY_RELAY_SECRET already set")
+        return False
+
+    try:
+        from hermes_cli.auth import resolve_nous_access_token
+
+        access_token = resolve_nous_access_token()
+    except Exception as exc:  # noqa: BLE001 - boot must survive a token failure
+        # No resolvable NAS identity (e.g. a self-hosted box that hasn't enrolled)
+        # -> nothing to provision with; skip quietly and let the gateway boot.
+        logger.warning("relay self-provision skipped: could not resolve Nous token (%s)", exc)
+        return False
+
+    platform, bot_id = relay_platform_identity()
+    # gatewayId default mirrors the enroll CLI's hostname-based slug.
+    import socket
+
+    try:
+        host = socket.gethostname().strip()
+    except Exception:  # noqa: BLE001
+        host = ""
+    gateway_id = os.environ.get("GATEWAY_RELAY_ID", "").strip() or f"gw-{host or 'hermes'}"
+    endpoint = relay_endpoint()
+    route_keys = relay_route_keys()
+
+    try:
+        result = _post_provision(
+            provision_url=_provision_url(dial_url),
+            access_token=access_token,
+            gateway_id=gateway_id,
+            platform=platform,
+            bot_id=bot_id,
+            gateway_endpoint=endpoint,
+            route_keys=route_keys,
+        )
+    except RuntimeError as exc:
+        logger.warning("relay self-provision failed (%s); gateway will boot without relay auth", exc)
+        return False
+
+    # Set creds in-process so register_relay_adapter() reads them from os.environ
+    # (the per-gateway secret authenticates the outbound WS upgrade). The delivery
+    # key is still issued by the connector and persisted for forward-compat, but
+    # inbound now rides the WS (no HTTP receiver), so it is not consumed here.
+    # Never logged.
+    os.environ["GATEWAY_RELAY_ID"] = str(result.get("gatewayId") or gateway_id)
+    os.environ["GATEWAY_RELAY_SECRET"] = str(result.get("secret") or "")
+    os.environ["GATEWAY_RELAY_DELIVERY_KEY"] = str(result.get("deliveryKey") or "")
+    tenant = str(result.get("tenant") or "")
+    logger.info(
+        "relay self-provisioned (gateway_id=%s tenant=%s routes=%d inbound=%s)",
+        os.environ["GATEWAY_RELAY_ID"],
+        tenant or "?",
+        len(route_keys),
+        "yes" if endpoint else "outbound-only",
+    )
+    return True
+
+
+def register_relay_adapter(force: bool = False, url: Optional[str] = None) -> bool:
+    """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()``.
+    """
+    resolved_url = url if url is not None else relay_url()
+    if not (force or resolved_url):
+        return False
+
+    from gateway.platform_registry import PlatformEntry, platform_registry
+    from gateway.relay.adapter import RelayAdapter
+    from gateway.relay.descriptor import CONTRACT_VERSION, CapabilityDescriptor
+
+    platform, bot_id = relay_platform_identity()
+
+    def _factory(config):
+        # Placeholder descriptor; replaced by the negotiated one at connect time
+        # when a transport is present. With no URL (force/test) the adapter is
+        # transport-less and keeps the placeholder.
+        placeholder = CapabilityDescriptor(
+            contract_version=CONTRACT_VERSION,
+            platform=platform,
+            label="Relay",
+            max_message_length=4096,
+            supports_draft_streaming=False,
+            supports_edit=True,
+            supports_threads=False,
+            markdown_dialect="plain",
+            len_unit="chars",
+        )
+        transport = None
+        if resolved_url:
+            from gateway.relay.ws_transport import WebSocketRelayTransport
+
+            gateway_id, upgrade_secret = relay_connection_auth()
+            transport = WebSocketRelayTransport(
+                resolved_url,
+                platform,
+                bot_id,
+                gateway_id=gateway_id,
+                upgrade_secret=upgrade_secret,
+            )
+        return RelayAdapter(config, placeholder, transport=transport)
+
+    platform_registry.register(
+        PlatformEntry(
+            name="relay",
+            label="Relay",
+            adapter_factory=_factory,
+            check_fn=lambda: True,
+            source="builtin",
+            emoji="\U0001f50c",
+        )
+    )
+    return True