@securecoms/agent-bridge 0.26.3 → 0.26.5

package/README.md

@@ -45,6 +45,17 @@ To install Node 24 manually instead:
 
 Always re-run the install command after upgrading Node — the background service pins the Node path it was installed with.
 
+### Harness minimum versions (0.26.5 and later)
+
+The bundled connectors give tools only to the agent owner's turns. Each harness must be able to block a tool call before it runs, so each has a minimum version:
+
+| Harness | Minimum version | Hook the connector relies on |
+|---------|-----------------|------------------------------|
+| OpenClaw | 2026.4.27 | `before_tool_call` that can block |
+| Hermes | v2026.9.24 | `pre_tool_call` veto |
+
+On an older harness the connector reports its tool veto as inactive and refuses every turn that has no tool grant, so non-owner rooms go quiet instead of running tools unchecked. `/healthz` shows `harness_tool_veto_active` (true, false, or null when no connector is attached), the authenticated `GET /v1/status` shows the harness name and version, and the daemon logs `harness.tool_veto_inactive` once when an attached harness cannot veto. After upgrading the package, re-run `agent-bridge wire --harness openclaw` (or re-copy the Hermes connector files) so the harness loads the new connector, then restart the harness gateway.
+
 ---
 
 ## Quickstart

package/connectors/hermes/adapter.py

@@ -71,11 +71,44 @@ from gateway.platforms.base import (
 )
 from gateway.config import Platform
 
+import securecoms_authz
 import securecoms_transport
 from securecoms_gate import resolve_bound_identity
 
 logger = logging.getLogger(__name__)
 
+# Tool gate (security fix 2026-10-05). Hermes runs every turn with the
+# owner's configured toolsets unless told otherwise, so a room member, a
+# partner-org member or another agent would reach the same shell/file tools
+# as the owner. The daemon's per-frame `authorization` block says who was
+# granted tools (securecoms_authz.tools_allowed); a turn without a grant runs
+# with tools disabled, enforced at two Hermes seams:
+#   1. toolsets_for_source(): the turn is OFFERED no toolsets (best effort,
+#      narrows what the model sees);
+#   2. a pre_tool_call veto registered by register(ctx): any tool call in a
+#      SecureComs turn that was not granted tools is BLOCKED (the enforcement).
+# The veto is only trusted when register(ctx) proves the running Hermes can
+# honour it (_TOOL_VETO_ACTIVE). When it cannot, a turn without a grant is
+# refused outright (acked, never handed to Hermes). Fail closed.
+_TURN_AUTHZ = securecoms_authz.TurnAuthzLedger()
+_TOOL_VETO_ACTIVE = False
+# gateway.session_context.get_session_env, bound by register(ctx): reads the
+# CURRENT turn's task-local session vars (platform, chat, user).
+_GET_SESSION_ENV = None
+# gateway.session_context.session_context_engaged when this Hermes has it;
+# None means "assume engaged" (an empty turn identity then blocks).
+_SESSION_ENGAGED = None
+# Reads Hermes's task-local cron ContextVar (session_context._CRON_SESSION);
+# None when this Hermes has none, and then no turn is exempt as cron.
+_IS_CRON = None
+# hermes_cli.__version__, reported to the daemon in the hello frame.
+_HARNESS_VERSION: Optional[str] = None
+# Channels already told that this agent cannot respond (veto inactive).
+_REFUSAL_NOTICE_SENT: set = set()
+_REFUSAL_NOTICE_MAX = 4096
+# Inbound frames seen without an authorization block (daemon too old).
+_FRAMES_WITHOUT_AUTHORIZATION = 0
+
 _PLUGIN_DIR = os.path.dirname(os.path.abspath(__file__))
 _BINDING_PATH = os.path.join(_PLUGIN_DIR, "securecoms.binding.json")
 _CONNECTIONS_DIR = os.path.expanduser("~/.securecoms/connections")
@@ -257,9 +290,31 @@ class SecureComsAdapter(BasePlatformAdapter):
         self.ws_url = target.ws_url
         self._token = target.token
         self._leave_hold()
+        await self._send_hello()
         await self._refresh_channels()
         return True
 
+    async def _send_hello(self) -> None:
+        """Tell the daemon which harness this is and whether its tool veto is
+        active (booleans/versions only), so /healthz shows it. A daemon that
+        predates the field ignores it."""
+        if self._ws is None:
+            return
+        try:
+            await self._ws.send_json({
+                "type": "hello",
+                "harness": {
+                    "name": "hermes",
+                    "version": _HARNESS_VERSION,
+                    "tool_veto": "active" if _TOOL_VETO_ACTIVE else "inactive",
+                },
+            })
+        except Exception as e:
+            logger.debug(
+                "SecureComs: hello send failed (error_class=%s)",
+                _error_class(e),
+            )
+
     def _enter_hold(self, reason: str) -> None:
         changed = self._hold_reason != reason
         self._hold_reason = reason
@@ -424,6 +479,24 @@ class SecureComsAdapter(BasePlatformAdapter):
         meta = self._channels.get(channel_id, {})
         chat_type = "dm" if meta.get("is_dm", True) else "group"
 
+        global _FRAMES_WITHOUT_AUTHORIZATION
+        if not isinstance(frame.get("authorization"), dict):
+            _FRAMES_WITHOUT_AUTHORIZATION += 1
+            if _FRAMES_WITHOUT_AUTHORIZATION % 100 == 1:
+                logger.warning(
+                    "SecureComs: inbound frame carries NO authorization block; the "
+                    "daemon predates the tool gate, so every turn runs without tools. "
+                    "Upgrade @securecoms/agent-bridge"
+                )
+        tools_allowed = securecoms_authz.tools_allowed(frame)
+        _TURN_AUTHZ.record(channel_id, sender_id, tools_allowed)
+        if not tools_allowed and not _TOOL_VETO_ACTIVE:
+            # This Hermes cannot be made to refuse tool calls, so a turn the
+            # daemon did not grant tools never reaches it. Acked by _pump.
+            logger.warning("SecureComs: refused a turn without a tool grant (tool veto unavailable)")
+            await self._notify_refused(channel_id, frame)
+            return
+
         source = self.build_source(
             chat_id=channel_id,
             chat_name=meta.get("name", channel_id),
@@ -431,6 +504,11 @@ class SecureComsAdapter(BasePlatformAdapter):
             user_id=sender_id,
             user_name=sender_id,
         )
+        if not tools_allowed and isinstance(text, str):
+            # An ungranted sender must never drive gateway commands. EVERY
+            # ungranted text is escaped: Hermes strips leading @url:/@file:
+            # refs before its "/" check, so "@url:x /reset" is a command too.
+            text = securecoms_authz.COMMAND_ESCAPE + text
         event = MessageEvent(
             text=text,
             message_type=MessageType.TEXT,
@@ -438,11 +516,52 @@ class SecureComsAdapter(BasePlatformAdapter):
             message_id=str(frame.get("message_id") or int(time.time() * 1000)),
             timestamp=datetime.now(),
         )
-        voice_prompt = voice_prompt_of(frame)
-        if voice_prompt is not None:
-            event.channel_prompt = voice_prompt
+        # Sender role rides as event metadata, never in the user text.
+        metadata = getattr(event, "metadata", None)
+        if not isinstance(metadata, dict):
+            metadata = {}
+        metadata["securecoms"] = {
+            "sender_role": securecoms_authz.sender_role(frame),
+            "tools_allowed": tools_allowed,
+        }
+        event.metadata = metadata
+        if not tools_allowed:
+            # Hermes's own switch for "this event may not resolve gateway
+            # commands or control prompts" (MessageEvent.allow_gateway_control).
+            event.allow_gateway_control = False
+        prompts = [p for p in (voice_prompt_of(frame), None if tools_allowed else securecoms_authz.NO_TOOLS_TURN_NOTE) if p]
+        if prompts:
+            event.channel_prompt = "\n\n".join(prompts)
         await self.handle_message(event)
 
+    async def _notify_refused(self, channel_id: str, frame: Dict[str, Any]) -> None:
+        """One short notice per channel that this agent cannot respond there.
+        Never to another agent (two refusing agents would answer each other)."""
+        if securecoms_authz.sender_role(frame) == "agent" or not channel_id:
+            return
+        if channel_id in _REFUSAL_NOTICE_SENT or len(_REFUSAL_NOTICE_SENT) >= _REFUSAL_NOTICE_MAX:
+            return
+        _REFUSAL_NOTICE_SENT.add(channel_id)
+        try:
+            await self.send(channel_id, securecoms_authz.REFUSED_TURN_NOTICE)
+        except Exception as e:
+            logger.debug(
+                "SecureComs: refusal notice failed (error_class=%s)",
+                _error_class(e),
+            )
+
+    def toolsets_for_source(self, source) -> Optional[list]:
+        """Hermes per-turn toolset override (gateway run_turn
+        _resolve_enabled_toolsets_for_source). None keeps the configured
+        toolsets: only for a (chat, sender) whose latest turn was granted
+        tools. Anything else, including an unknown source, gets the no-tools
+        override."""
+        chat_id = getattr(source, "chat_id", None)
+        user_id = getattr(source, "user_id", None)
+        if _TURN_AUTHZ.tools_allowed(chat_id, user_id):
+            return None
+        return list(securecoms_authz.NO_TOOLS_TOOLSETS)
+
     # ── Outbound ──────────────────────────────────────────────────────────
 
     _BLOCK_SEQ_MAX = 1000
@@ -542,8 +661,88 @@ def check_requirements() -> bool:
     return os.path.isfile(os.getenv("SECURECOMS_CONNECTION_FILE") or _BINDING_PATH)
 
 
+def _securecoms_pre_tool_call(**_kwargs):
+    """Hermes pre_tool_call hook: block every tool call in a SecureComs turn
+    that the daemon did not grant tools, and any call whose turn identity is
+    empty in an engaged gateway. No opinion on other platforms."""
+    get_env = _GET_SESSION_ENV
+    if get_env is None:
+        return {"action": "block", "message": securecoms_authz.TOOL_VETO_MESSAGE}
+    return securecoms_authz.pre_tool_call_decision(get_env, _TURN_AUTHZ, _SESSION_ENGAGED, _IS_CRON)
+
+
+def _install_tool_veto(ctx) -> bool:
+    """Register the pre_tool_call veto and report whether this Hermes can
+    honour it. All three must hold, or the veto is not trusted:
+      - pre_tool_call results can BLOCK (hermes_cli.plugins exposes the block
+        directive API; older Hermes treated the hook as an observer only);
+      - the turn's session is task-local (gateway.session_context), so the
+        hook attributes a tool call to the right turn rather than to whatever
+        turn last wrote os.environ;
+      - MessageEvent has allow_gateway_control (else room members could
+        still drive gateway commands);
+      - ctx.register_hook accepted the callback.
+    Cron exemption is read only from session_context._CRON_SESSION.
+    """
+    global _GET_SESSION_ENV, _SESSION_ENGAGED, _HARNESS_VERSION, _IS_CRON
+    try:
+        import hermes_cli
+
+        version = getattr(hermes_cli, "__version__", None)
+        _HARNESS_VERSION = version if isinstance(version, str) else None
+    except Exception:
+        _HARNESS_VERSION = None
+    try:
+        from hermes_cli import plugins as hermes_plugins
+
+        if not any(
+            hasattr(hermes_plugins, name)
+            for name in (
+                "_get_pre_tool_call_directive_details",
+                "get_pre_tool_call_directive",
+                "get_pre_tool_call_block_message",
+            )
+        ):
+            return False
+        from gateway import session_context
+        from gateway.session_context import get_session_env
+
+        engaged = getattr(session_context, "session_context_engaged", None)
+        _SESSION_ENGAGED = engaged if callable(engaged) else None
+        cron_var = getattr(session_context, "_CRON_SESSION", None)
+        if cron_var is not None and callable(getattr(cron_var, "get", None)):
+            _IS_CRON = lambda: cron_var.get() == "1"  # noqa: E731
+        else:
+            _IS_CRON = None
+
+        # Without MessageEvent.allow_gateway_control an ungranted turn could
+        # still drive gateway commands, so this Hermes is not trusted either.
+        if "allow_gateway_control" not in getattr(MessageEvent, "__dataclass_fields__", {}) and not hasattr(
+            MessageEvent, "allow_gateway_control"
+        ):
+            return False
+
+        register_hook = getattr(ctx, "register_hook", None)
+        if not callable(register_hook):
+            return False
+        _GET_SESSION_ENV = get_session_env
+        register_hook("pre_tool_call", _securecoms_pre_tool_call)
+        return True
+    except Exception as e:
+        logger.warning(
+            "SecureComs: tool veto unavailable (error_class=%s)", _error_class(e)
+        )
+        return False
+
+
 def register(ctx):
     """Plugin entry point: called by the Hermes plugin system."""
+    global _TOOL_VETO_ACTIVE
+    _TOOL_VETO_ACTIVE = _install_tool_veto(ctx)
+    if not _TOOL_VETO_ACTIVE:
+        logger.warning(
+            "SecureComs: tool veto inactive; turns without a tool grant will be refused"
+        )
     ctx.register_platform(
         name="securecoms",
         label="SecureComs",

package/connectors/hermes/securecoms_authz.py

@@ -0,0 +1,190 @@
+"""
+Per-turn tool authorization for the SecureComs Hermes connector.
+
+Gateway-import-free (like securecoms_gate.py / securecoms_transport.py) so it
+is unit tested in the backend CI venv.
+
+The daemon attaches an ``authorization`` block to every inbound frame
+(``BridgeAgent.authorizationFor`` in packages/connect-agent-bridge, derived
+from server-authenticated roster data, never from message plaintext):
+
+    {"version": 1, "audience": ..., "sender_membership": "active"|"unknown",
+     "tool_grants": [{"tool": ..., "mode": ...}, ...]}
+
+``tool_grants`` is non-empty ONLY for a DM's single human counterpart whom the
+server marks as the agent's owner (``is_agent_owner``), or a relayed voice
+turn whose speaker is that person. The daemon pins that counterpart per
+channel, so the owner distinction rests on the server's flag: a backend that
+mis-sets it would grant a DM member tools (review H2; binding the owner
+identity outside server control is an open follow-up). Every other sender (room
+members, other-org members, other agents, an older daemon that sends no
+block, a malformed block) gets an empty list. This module turns that into one
+decision per turn: tools on, or tools off. It fails closed: anything it does
+not positively recognise as a grant is "no tools".
+
+Hermes cannot express the daemon's per-tool grants (current_time, web_search)
+as its own toolsets, so a granted turn keeps the owner's configured Hermes
+toolsets unchanged and an ungranted turn gets none.
+"""
+
+from collections import OrderedDict
+from typing import Any, Callable, Dict, Optional
+
+PLATFORM_ID = "securecoms"
+
+# Becomes the tool result when Hermes vetoes a call (pre_tool_call "block").
+TOOL_VETO_MESSAGE = (
+    "Tool use is disabled for this message: SecureComs grants tools only to "
+    "this agent's owner in their direct message. Answer in text only."
+)
+
+# Ephemeral per-turn system note (MessageEvent.channel_prompt) for a turn that
+# runs without tools, so the model answers in text rather than trying tools.
+NO_TOOLS_TURN_NOTE = (
+    "Tools are disabled for this message because its sender is not this "
+    "agent's owner in a direct message. Answer in text only and do not try "
+    "to call any tool."
+)
+
+# Posted ONCE per channel (per process) when a turn without a tool grant is
+# refused because this Hermes cannot veto tool calls: the whole turn is
+# refused, so the room is told rather than left with a silent agent.
+REFUSED_TURN_NOTICE = "I can't respond in this room until my owner updates me."
+
+# Prefixed to an ungranted message that starts with "/" so the Hermes
+# gateway never reads it as a command (WORD JOINER: not whitespace, so
+# Hermes's lstrip() keeps it; invisible when rendered).
+COMMAND_ESCAPE = "\u2060"
+
+# Hermes ``toolsets_for_source`` override for a turn without tools. Hermes
+# ignores an EMPTY override (it falls back to the configured toolsets), so the
+# override is a non-empty list. ``no_mcp`` is Hermes's own sentinel that turns
+# off every MCP server; it names no built-in toolset, so it resolves to no
+# built-in tools either. This only narrows what the model is offered; the
+# pre_tool_call veto is what refuses a call.
+NO_TOOLS_TOOLSETS = ("no_mcp",)
+
+_ROLE_BY_AUDIENCE = {
+    "owner_dm": "owner",
+    "team_room": "member",
+    "other_human_dm": "member",
+    "partner_room": "other_org",
+    "agent_to_agent": "agent",
+}
+
+
+def _valid_block(frame: Any) -> Optional[Dict[str, Any]]:
+    if not isinstance(frame, dict):
+        return None
+    block = frame.get("authorization")
+    if not isinstance(block, dict):
+        return None
+    if block.get("version") != 1 or isinstance(block.get("version"), bool):
+        return None
+    if block.get("sender_membership") != "active":
+        return None
+    return block
+
+
+def _is_grant(entry: Any) -> bool:
+    return isinstance(entry, dict) and isinstance(entry.get("tool"), str) and entry["tool"] != ""
+
+
+def tools_allowed(frame: Any) -> bool:
+    """True only when the daemon granted this turn at least one tool."""
+    block = _valid_block(frame)
+    if block is None:
+        return False
+    grants = block.get("tool_grants")
+    if not isinstance(grants, list) or not grants:
+        return False
+    return all(_is_grant(g) for g in grants)
+
+
+def sender_role(frame: Any) -> str:
+    """owner / member / other_org / agent / unknown, from the daemon's
+    audience. Descriptive metadata for Hermes, never an authorization input:
+    tools follow ``tools_allowed`` alone."""
+    block = _valid_block(frame)
+    if block is None:
+        return "unknown"
+    return _ROLE_BY_AUDIENCE.get(block.get("audience"), "unknown")
+
+
+class TurnAuthzLedger:
+    """The tool decision of the latest inbound frame per (chat_id, sender).
+
+    Hermes runs a turn later, on its own task, so the decision is recorded at
+    dispatch and looked up when a tool is about to run (by the chat and user
+    Hermes binds to that turn's session). Unrecorded or evicted keys have no
+    tools.
+    """
+
+    def __init__(self, max_entries: int = 4096):
+        self._max = max_entries
+        self._entries: "OrderedDict[tuple, bool]" = OrderedDict()
+        # Every SecureComs chat id ever recorded. Never evicted (one entry per
+        # channel), so a chat whose decision was evicted is still known to be
+        # SecureComs and its tool calls are still gated.
+        self._chats: set = set()
+
+    def record(self, chat_id: Any, user_id: Any, allowed: bool) -> None:
+        key = (chat_id, user_id)
+        if isinstance(chat_id, str) and chat_id:
+            self._chats.add(chat_id)
+        self._entries.pop(key, None)
+        self._entries[key] = allowed is True
+        while len(self._entries) > self._max:
+            self._entries.popitem(last=False)
+
+    def knows_chat(self, chat_id: Any) -> bool:
+        """True when some recorded turn came from this chat id."""
+        if not isinstance(chat_id, str) or not chat_id:
+            return False
+        return chat_id in self._chats
+
+    def tools_allowed(self, chat_id: Any, user_id: Any) -> bool:
+        if not isinstance(chat_id, str) or not chat_id or not isinstance(user_id, str) or not user_id:
+            return False
+        return self._entries.get((chat_id, user_id)) is True
+
+
+def pre_tool_call_decision(
+    get_session_env: Callable[..., str],
+    ledger: TurnAuthzLedger,
+    session_engaged: Optional[Callable[[], bool]] = None,
+    is_cron: Optional[Callable[[], bool]] = None,
+) -> Optional[Dict[str, str]]:
+    """The Hermes ``pre_tool_call`` directive for the current turn.
+
+    - A SecureComs turn (platform label, or a chat id this connector
+      recorded): no opinion only when that chat and sender were granted
+      tools, else block.
+    - A turn with an EMPTY platform, in a process whose gateway has bound
+      sessions (``session_engaged``, default engaged): block, whatever the
+      chat and user say. A tool call that lost its task-local session cannot
+      be attributed, so it must not be assumed to be someone else's. The one
+      exception is a cron turn identified by ``is_cron``, which must read
+      Hermes's task-local cron ContextVar; the environment never counts
+      (None = no exemption).
+    - Any other platform: no opinion.
+    A failure to read the session blocks.
+    """
+    try:
+        platform = get_session_env("HERMES_SESSION_PLATFORM", "")
+        chat_id = get_session_env("HERMES_SESSION_CHAT_ID", "")
+        user_id = get_session_env("HERMES_SESSION_USER_ID", "")
+        if platform == PLATFORM_ID or ledger.knows_chat(chat_id):
+            if ledger.tools_allowed(chat_id, user_id):
+                return None
+        elif platform == "":
+            engaged = True if session_engaged is None else session_engaged() is not False
+            if not engaged:
+                return None
+            if is_cron is not None and is_cron() is True:
+                return None
+        else:
+            return None
+    except Exception:
+        pass
+    return {"action": "block", "message": TOOL_VETO_MESSAGE}