@securecoms/agent-bridge 0.6.0 → 0.8.0

package/connectors/hermes/securecoms_transport.py

@@ -0,0 +1,257 @@
+# packages/connect-agent-bridge/connectors/hermes/securecoms_transport.py
+#
+# Contract transport layer for the Hermes connector - the daemon-loopback
+# client half of the ADR-0009 connector contract. Python port (in spirit; see
+# tests/test_securecoms_transport.py's header) of ../openclaw/openclaw-entry.js's
+# LoopbackChannel: resolve_target/probe_and_gate replace _resolveConnection/
+# _probeAndGate, should_drop_inbound replaces the "own sender" echo check in
+# the WS "message" handler, and ChannelStatusManager replaces the ad-hoc
+# reportStatus("working")/reportStatus("idle") pair scattered through
+# _handleInbound.
+#
+# Audit constraints (task-2-brief.md):
+#   - ZERO `gateway.*` imports: this module is a plain daemon HTTP/WS client,
+#     never a gateway/plugin-registry abstraction. Enforced by a source-scan
+#     trip-wire in tests/test_securecoms_transport.py.
+#   - `session` is INJECTED (an aiohttp.ClientSession or a fake with the same
+#     `async def get(url)` shape) so no `aiohttp` import is needed here or in
+#     tests; `resolve_target` itself is pure file reads, no network at all.
+#   - Per-attempt re-resolution: `resolve_target`/`probe_and_gate` cache
+#     NOTHING between calls - every attempt re-reads the binding, the
+#     connection file, and the token file from scratch, so a moved port or a
+#     rotated token is picked up on the very next call (spec S4.2 step 6 ->
+#     step 1; audit C3).
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Awaitable, Callable, Mapping, NamedTuple, Optional, Tuple
+
+from securecoms_gate import evaluate_gate, resolve_bound_identity
+
+
+class ResolvedTarget(NamedTuple):
+    bridge_url: str  # http(s):// base - target for /healthz, /v1/send, /v1/status
+    ws_url: str  # ws(s):// URL as written by the daemon - target for the WS connect
+    token: str  # bearer token, read from token_file NOW (never cached)
+    identity_id: str  # identity_id as recorded IN THE CONNECTION FILE (file identity)
+
+
+def _ws_to_http(ws_url: str) -> str:
+    """ws://host:port/v1/ws -> http://host:port ; wss:// -> https://.
+
+    Mirrors openclaw-entry.js's `bridge_url.replace(/^ws/, "http").replace(/\\/v1\\/ws$/, "")`.
+    """
+    if ws_url.startswith("wss://"):
+        http_url = "https://" + ws_url[len("wss://"):]
+    elif ws_url.startswith("ws://"):
+        http_url = "http://" + ws_url[len("ws://"):]
+    else:
+        http_url = ws_url
+    if http_url.endswith("/v1/ws"):
+        http_url = http_url[: -len("/v1/ws")]
+    return http_url
+
+
+def _resolve_target_for_identity(
+    bound_identity: Optional[str],
+    read_file_text: Callable[[str], str],
+    connections_dir: str,
+) -> Optional[ResolvedTarget]:
+    """connections_dir/<bound_identity>.json -> (bridge_url, token_file,
+    identity_id) -> token read NOW. Shared body for resolve_target (which
+    derives bound_identity from env/binding) and probe_and_gate_bound (which
+    takes an already-fixed bound_identity and never derives it) - see the
+    BINDING-STABILITY fold note on probe_and_gate_bound below.
+
+    Returns None on ANY absence/partial/unreadable condition along the
+    chain - no bound_identity, no connection file, a connection file that
+    parses but is missing/blank bridge_url or token_file (e.g. daemon
+    mid-write), or a token_file that can't be read yet. Never raises: the
+    caller's job is to hold and retry, not to catch exceptions from here
+    (spec S4.2).
+    """
+    if not bound_identity:
+        return None
+
+    conn_path = os.path.join(connections_dir, f"{bound_identity}.json")
+    try:
+        conn = json.loads(read_file_text(conn_path))
+    except Exception:
+        return None
+    if not isinstance(conn, dict):
+        return None
+
+    ws_url = conn.get("bridge_url")
+    token_file = conn.get("token_file")
+    identity_id = conn.get("identity_id")
+    if not ws_url or not token_file or not identity_id:
+        return None
+
+    try:
+        token = read_file_text(token_file)
+    except Exception:
+        return None
+    token = token.strip() if isinstance(token, str) else ""
+    if not token:
+        return None
+
+    return ResolvedTarget(
+        bridge_url=_ws_to_http(ws_url),
+        ws_url=ws_url,
+        token=token,
+        identity_id=identity_id,
+    )
+
+
+def resolve_target(
+    env: Mapping[str, str],
+    read_file_text: Callable[[str], str],
+    binding_path: str,
+    connections_dir: str,
+) -> Optional[ResolvedTarget]:
+    """bound_identity (env or binding file) -> connections_dir/<id>.json
+    (bridge_url, token_file, identity_id) -> token read NOW.
+
+    Re-derives bound_identity from env/binding_path on every call - fine for
+    this pure lookup helper (and for probe_and_gate's per-call convenience
+    wrapper below), but the WRONG entrypoint for a running connector's
+    per-attempt reconnect path: see probe_and_gate_bound.
+    """
+    bound_identity = resolve_bound_identity(env, read_file_text, binding_path)
+    return _resolve_target_for_identity(bound_identity, read_file_text, connections_dir)
+
+
+async def probe_and_gate_bound(
+    session,
+    bound_identity: Optional[str],
+    read_file_text: Callable[[str], str],
+    connections_dir: str,
+) -> Tuple[Optional[ResolvedTarget], str]:
+    """probe_and_gate, but for a bound_identity the CALLER already resolved
+    and is holding fixed - this function never reads env or a binding file,
+    so it structurally cannot re-bind (BINDING-STABILITY fold, task-3
+    review): the contract requires bound_identity be decided exactly ONCE
+    for a connector's process life (2026-07-19 spec:153); re-deriving it on
+    every reconnect attempt (the old probe_and_gate's per-call behavior)
+    would let a binding-file rewrite silently re-bind a running connector to
+    a different agent mid-session. Callers that own a long-lived bound
+    identity (adapter.py's SecureComsAdapter) resolve it once - e.g. at
+    connect() - and pass the SAME value into every subsequent reconnect
+    attempt via this entrypoint.
+
+    Returns (target, "") on success, or (None, reason) on any hold/refuse:
+    unwired, not-yet-resolvable, daemon unreachable, or a two-anchor gate
+    mismatch. Never opens a websocket - that stays entirely the caller's
+    job, once (and only once) this returns a non-None target.
+    """
+    if not bound_identity:
+        return None, "unwired: no binding (refusing to guess)"
+
+    target = _resolve_target_for_identity(bound_identity, read_file_text, connections_dir)
+    if target is None:
+        return None, "not-ready: no connection file / token yet"
+
+    try:
+        resp = await session.get(f"{target.bridge_url}/healthz")
+        health = await resp.json()
+    except Exception as e:
+        return None, f"daemon unreachable at {target.bridge_url}: {e}"
+
+    healthz_identity = health.get("identity_id") if isinstance(health, dict) else None
+    ok, reason = evaluate_gate(bound_identity, target.identity_id, healthz_identity)
+    if not ok:
+        return None, reason
+
+    return target, ""
+
+
+async def probe_and_gate(
+    session,
+    env: Mapping[str, str],
+    read_file_text: Callable[[str], str],
+    binding_path: str,
+    connections_dir: str,
+) -> Tuple[Optional[ResolvedTarget], str]:
+    """Convenience wrapper: resolve bound_identity from env/binding_path
+    ONCE per call, then delegate to probe_and_gate_bound. Kept for callers
+    (and existing tests) that want single-call per-attempt re-resolution
+    semantics from env/binding_path; a long-lived connector process should
+    prefer resolving bound_identity itself exactly once and calling
+    probe_and_gate_bound directly on every attempt (see its docstring).
+    """
+    bound_identity = resolve_bound_identity(env, read_file_text, binding_path)
+    return await probe_and_gate_bound(session, bound_identity, read_file_text, connections_dir)
+
+
+def should_drop_inbound(frame: dict, bound_identity: str) -> bool:
+    """Echo guard: never feed our own sends back into the agent.
+
+    True only when the frame carries a truthy sender_id that equals a
+    truthy bound_identity - matches openclaw-entry.js's
+    `frame.sender_id && this._ownIdentity && frame.sender_id === this._ownIdentity`.
+    """
+    sender_id = frame.get("sender_id")
+    return bool(sender_id) and bool(bound_identity) and sender_id == bound_identity
+
+
+class ChannelStatusManager:
+    """Per-channel working/idle status emitter, decoupled from any one reply
+    turn (unlike openclaw-entry.js's inline reportStatus("working")/("idle")
+    pair, which only spans a single dispatch). States are limited to
+    "idle"|"working" - this manager never emits "stalled"/"error" (those are
+    daemon-side WS status states outside this manager's job; see
+    src/ws-server.ts ~295-320).
+
+    now() is injected so tests can drive time deterministically (a FakeClock)
+    instead of racing real wall-clock sleeps.
+    """
+
+    def __init__(
+        self,
+        send_frame: Callable[[dict], Awaitable[None]],
+        *,
+        refresh_s: float = 10.0,
+        idle_after_s: float = 20.0,
+        now: Callable[[], float],
+    ) -> None:
+        self._send_frame = send_frame
+        self._refresh_s = refresh_s
+        self._idle_after_s = idle_after_s
+        self._now = now
+        # channel_id -> {"last_emit": float, "deadline": float}. Presence in
+        # this dict means "currently working"; on_reply_posted/idle-via-tick
+        # both pop the entry, so presence alone doubles as the state.
+        self._working: dict[str, dict] = {}
+
+    async def _emit(self, channel_id: str, state: str) -> None:
+        await self._send_frame({"type": "status", "channel_id": channel_id, "state": state})
+
+    async def on_typing(self, channel_id: str) -> None:
+        now = self._now()
+        st = self._working.get(channel_id)
+        if st is None:
+            # First call for this channel (or the first since it last went
+            # idle): emit "working" unconditionally. NEVER emit "idle" here -
+            # doing so would flash the UI strip (task-2-brief mutation #3).
+            await self._emit(channel_id, "working")
+            self._working[channel_id] = {"last_emit": now, "deadline": now + self._idle_after_s}
+            return
+        # Already working: always push the silence deadline out, but only
+        # re-emit the frame at most once per refresh_s (the daemon-side
+        # publish is expensive - see openclaw-entry.js's reportStatus comment).
+        st["deadline"] = now + self._idle_after_s
+        if now - st["last_emit"] >= self._refresh_s:
+            await self._emit(channel_id, "working")
+            st["last_emit"] = now
+
+    async def on_reply_posted(self, channel_id: str) -> None:
+        await self._emit(channel_id, "idle")
+        self._working.pop(channel_id, None)
+
+    async def tick(self) -> None:
+        now = self._now()
+        for channel_id in [cid for cid, st in self._working.items() if now >= st["deadline"]]:
+            await self._emit(channel_id, "idle")
+            self._working.pop(channel_id, None)

package/connectors/hermes/tests/conftest.py

@@ -0,0 +1,23 @@
+# packages/connect-agent-bridge/connectors/hermes/tests/conftest.py
+#
+# securecoms_gate.py/securecoms_transport.py/adapter.py import each other as
+# bare top-level modules ("from securecoms_gate import ...", "import
+# securecoms_transport") - the shape Hermes's own
+# plugin loader uses (each plugin dir is spec_from_file_location'd, not
+# imported as a dotted package). Once connectors/hermes/__init__.py exists
+# (required so Hermes can load this directory as a plugin), pytest's default
+# "prepend" import mode would otherwise walk up the __init__.py chain and
+# import test modules as `hermes.tests.test_x`, executing
+# connectors/hermes/__init__.py (which imports adapter.py, which imports
+# gateway.* - absent from this venv) as a side effect of merely collecting
+# tests. --import-mode=importlib (pytest.ini) avoids that dotted-package
+# walk; this conftest just puts connectors/hermes on sys.path so the bare
+# top-level imports inside securecoms_gate.py/securecoms_transport.py/
+# adapter.py keep resolving.
+
+import os
+import sys
+
+_HERMES_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if _HERMES_DIR not in sys.path:
+    sys.path.insert(0, _HERMES_DIR)