mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-11-17 04:11:35 +00:00
docs/ was not the documentation site; it was a grab bag of long-form design notes, wire contracts and observability guides that landed with feature PRs because their authors needed somewhere to put them. Root AGENTS.md already says long-form dev docs live in website/docs/developer-guide/; this moves the 14 living documents there (or to the matching user-guide section) so they are published, searchable and linked from the sidebar instead of being found by grep only. Developer guide: micro-compaction, gateway-session-lifecycle (was session-lifecycle), state-db-recovery, multiplexing-gateway, chronos-managed-cron-contract, relay-connector-contract, observer-hooks (was observability/README), gateway-monitoring (observability/monitoring), relay-shared-metrics, middleware, streaming-tts, billing-lifecycle. User guide: egress/network-isolation (was security/network-egress- isolation), features/kanban-multi-gateway (was kanban/multi-gateway). Each page got title/description frontmatter and a sidebar entry; repo- relative links became site links or GitHub blob URLs; two MDX brace hazards escaped. Every in-tree pointer (module docstrings, config comments, the relay conformance test's Path, the monitoring-doc test, gateway-internals, cron-internals, kanban docs, .dockerignore, AGENTS.md) now names the new location. `docusaurus build` passes with no unresolved links on the moved pages.
99 lines
4.4 KiB
Python
99 lines
4.4 KiB
Python
"""Relay transport protocol — the gateway<->connector wire contract. EXPERIMENTAL.
|
|
|
|
The ``RelayAdapter`` delegates all wire I/O to a ``RelayTransport``. The gateway
|
|
dials OUT to the connector, so production is a WebSocket client (``ws_transport.py``)
|
|
and tests use an in-memory stub (``tests/gateway/relay/stub_connector.py``). This
|
|
module defines the protocol surface only. May change without a deprecation cycle
|
|
until >=2 Class-1 platforms validate it. See website/docs/developer-guide/relay-connector-contract.md.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from typing import Any, Awaitable, Callable, Dict, Optional, Protocol, runtime_checkable
|
|
|
|
from gateway.platforms.event import MessageEvent
|
|
from gateway.relay.descriptor import CapabilityDescriptor
|
|
|
|
# Callback the transport invokes for each inbound normalized event.
|
|
InboundHandler = Callable[[MessageEvent], Awaitable[None]]
|
|
|
|
# Callback for each forwarded passthrough request (§5.1): ``(forward, buffer_id)``.
|
|
# ``forward`` is a ws_transport.PassthroughForward, typed Any here because
|
|
# ws_transport imports FROM this module; ``buffer_id`` (§5.3 buffered flip) is
|
|
# acked by the handler after durable handoff.
|
|
PassthroughHandler = Callable[[Any, Optional[str]], Awaitable[None]]
|
|
|
|
|
|
@runtime_checkable
|
|
class RelayTransport(Protocol):
|
|
"""Full gateway<->connector transport contract."""
|
|
|
|
async def connect(self) -> bool:
|
|
"""Open the connection to the connector; return True on success."""
|
|
...
|
|
|
|
async def disconnect(self) -> None:
|
|
...
|
|
|
|
async def handshake(self) -> CapabilityDescriptor:
|
|
"""Return the capability descriptor the connector advertises."""
|
|
...
|
|
|
|
def set_inbound_handler(self, handler: InboundHandler) -> None:
|
|
...
|
|
|
|
def set_passthrough_handler(self, handler: "PassthroughHandler") -> None:
|
|
"""Register the callback for each forwarded passthrough request (§5.1).
|
|
|
|
The connector answers the provider's edge ACK itself, then forwards the real
|
|
request over this same outbound socket (a hosted gateway has no public
|
|
inbound port). Optional on a transport (a stub may not implement it).
|
|
"""
|
|
...
|
|
|
|
async def send_outbound(
|
|
self, action: Dict[str, Any], *, platform: Optional[str] = None
|
|
) -> Dict[str, Any]:
|
|
"""Carry an outbound action (send/edit/typing) to the connector.
|
|
|
|
Returns a result dict; for ``op == "send"`` it carries ``success`` and
|
|
optionally ``message_id`` / ``error``. ``platform`` tags WHICH fronted
|
|
platform this reply targets (the transport resolves the matching botId);
|
|
omitted ⇒ the connector uses the session's default platform.
|
|
"""
|
|
...
|
|
|
|
async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
|
|
"""Proxy a chat-info lookup to the connector."""
|
|
...
|
|
|
|
async def send_interrupt(self, session_key: str, reason: Optional[str] = None) -> None:
|
|
"""Route a mid-turn /stop to the connector for ``session_key`` (OUTBOUND
|
|
direction; the actual cancellation happens when the connector echoes an
|
|
interrupt inbound down the socket owning that session)."""
|
|
...
|
|
|
|
async def go_idle(self, timeout_s: float = 10.0) -> bool:
|
|
"""Ask the connector to flip this instance to buffered-only (§5.3).
|
|
|
|
Sends ``going_idle`` and awaits the connector-authoritative ``going_idle_ack``
|
|
(live delivery stopped; inbound now buffers for replay on reconnect). True on
|
|
ack, False on timeout / not-connected — the caller closes regardless.
|
|
Optional on a transport; part of the gateway's EXISTING drain transition.
|
|
"""
|
|
...
|
|
|
|
async def send_follow_up(
|
|
self, action: Dict[str, Any], *, platform: Optional[str] = None
|
|
) -> Dict[str, Any]:
|
|
"""Act on a shared-identity capability bound to a session (A2 outbound).
|
|
|
|
A credential acting on the SHARED bot identity (e.g. a Discord interaction
|
|
follow-up token) NEVER reaches the gateway: the connector vaults it keyed by
|
|
session and the gateway issues a SEMANTIC action (``op == "follow_up"``,
|
|
``session_key``, ``kind`` e.g. ``"discord.interaction_token"``, ``content``,
|
|
optional ``metadata``). Returns ``{success, message_id?, error?}``; ``success``
|
|
is False when the capability is absent/expired or the tenant mismatches —
|
|
nothing to retry with (a leaked gateway holds zero capability material).
|
|
"""
|
|
...
|