@securecoms/agent-bridge 0.38.0 → 0.39.0

package/connectors/hermes/adapter.py

@@ -140,6 +140,17 @@ _ACCEPT_POLL_S = 0.02
 # One warning per process when this Hermes lacks the acceptance signal.
 _TURN_TRACKING_WARNED = False
 
+# H0: Hermes session key -> [(ledger token, runner key)] for every ungranted
+# event dispatched into that session and not yet released. Module-level, like
+# _TURN_AUTHZ, so a replaced adapter instance or a task cancelled before its
+# first step cannot strand a count: the next completion that finds the session
+# idle releases it, whichever adapter instance observes it.
+_ATTACHED: Dict[Any, list] = {}
+# One warning per process each: an idle input Hermes does not expose (so no
+# count can be released), and H0.2b's shared room sessions.
+_IDLE_INPUTS_WARNED = False
+_SHARED_ROOMS_WARNED = False
+
 # Hermes's Signal adapter mapping (_MEDIA_TYPE_BY_MIME_PREFIX): first matching
 # prefix wins; anything else is a DOCUMENT so Hermes surfaces the file path.
 _MEDIA_TYPE_BY_MIME_PREFIX = (("audio/", "VOICE"), ("image/", "PHOTO"), ("video/", "VIDEO"))
@@ -306,6 +317,16 @@ class SecureComsAdapter(BasePlatformAdapter):
             self._send_status_frame, now=time.monotonic
         )
 
+        # H0.2b: Hermes shares ONE room session across every sender when
+        # group_sessions_per_user is off; every room turn is then ungranted.
+        self._room_sessions_shared = self._group_sessions_shared()
+
+    def _group_sessions_shared(self) -> bool:
+        extra = getattr(self.config, "extra", None)
+        if not isinstance(extra, dict):
+            return True
+        return extra.get("group_sessions_per_user", True) is not True
+
     @property
     def name(self) -> str:
         return "SecureComs"
@@ -327,6 +348,14 @@ class SecureComsAdapter(BasePlatformAdapter):
         """
         del is_reconnect  # accepted for contract parity; nothing to preserve
         self._stopped = False
+        self._room_sessions_shared = self._group_sessions_shared()
+        global _SHARED_ROOMS_WARNED
+        if self._room_sessions_shared and not _SHARED_ROOMS_WARNED:
+            _SHARED_ROOMS_WARNED = True
+            logger.warning(
+                "SecureComs: group_sessions_per_user is off, so a room shares one Hermes session "
+                "across senders; every room turn runs without tools"
+            )
 
         # BINDING-STABILITY fold: resolve bound_identity here, ONCE, for the
         # entire process life of this adapter instance. Every subsequent
@@ -523,7 +552,9 @@ class SecureComsAdapter(BasePlatformAdapter):
             if r.status == 200:
                 for c in await r.json():
                     self._channels[c["channel_id"]] = {
-                        "name": c.get("name") or c["channel_id"],
+                        # Member-chosen and reaches the prompt (chat_name,
+                        # get_chat_info): sanitized once, here (R3).
+                        "name": securecoms_transport.display_name(c.get("name")) or c["channel_id"],
                         "is_dm": bool(c.get("is_dm")),
                     }
 
@@ -708,15 +739,127 @@ class SecureComsAdapter(BasePlatformAdapter):
 
     async def on_processing_complete(self, event: Any, outcome: Any) -> None:
         """Hermes lifecycle hook (base.py:3448): record the outcome on the
-        event for _await_acceptance, then keep the base behaviour."""
+        event for _await_acceptance, run the H0 release check, then keep the
+        base behaviour."""
         try:
             event._securecoms_outcome = getattr(outcome, "name", None) or "UNKNOWN"
         except Exception:
             pass
+        try:
+            self._settle_on_completion(event)
+        except Exception as e:
+            logger.warning(
+                "SecureComs: ungranted-turn release check failed; its sender stays without tools "
+                "(error_class=%s)",
+                _error_class(e),
+            )
         base = getattr(super(), "on_processing_complete", None)
         if callable(base):
             await base(event, outcome)
 
+    # ── H0: ungranted turns in flight ─────────────────────────────────────
+    #
+    # Hermes v2026.9.24 (read on the Mini): on_processing_complete fires once
+    # per started task, for the event that started it only (base.py:4520-4540),
+    # before the debounce flush and the pending pop. An event can reach a turn
+    # without starting it (redirect, steer, base merge, runner FIFO, debounce),
+    # and an event that DID start its own base task can still be parked by the
+    # runner behind a pending sentinel (run_inbound.py:690-697) or swapped for
+    # an orphaned FIFO head, so its own completion does not prove its text has
+    # run. Every ungranted event's count is therefore attached to its Hermes
+    # session at dispatch and comes down only when the event never reached
+    # Hermes, or at a moment its session is idle: no other running task, no
+    # command guard, nothing pending or debounced, an empty runner FIFO and no
+    # runner turn. Never on a grant. Anything unreadable counts as busy.
+
+    def _session_key_of(self, event: Any) -> Optional[str]:
+        key_fn = getattr(self, "_event_session_key", None)
+        if not callable(key_fn):
+            return None
+        try:
+            key = key_fn(event)
+        except Exception:
+            return None
+        return key if isinstance(key, str) and key else None
+
+    def _runner_key_of(self, event: Any) -> Optional[str]:
+        runner = getattr(self, "gateway_runner", None)
+        key_fn = getattr(runner, "_session_key_for_source", None)
+        if not callable(key_fn):
+            return None
+        try:
+            key = key_fn(event.source)
+        except Exception:
+            return None
+        return key if isinstance(key, str) and key else None
+
+    @staticmethod
+    def _warn_idle_inputs_missing() -> None:
+        global _IDLE_INPUTS_WARNED
+        if _IDLE_INPUTS_WARNED:
+            return
+        _IDLE_INPUTS_WARNED = True
+        logger.warning(
+            "SecureComs: this Hermes does not expose its session idle state; a sender whose "
+            "turn ran without tools stays without tools"
+        )
+
+    def _session_idle(self, session_key: str, completing: Any, runner_keys=()) -> bool:
+        """True only when nothing in this Hermes session can still be
+        processing an event's text. ``completing`` is the task whose
+        on_processing_complete is running (it is ending, so it is not busy)."""
+        try:
+            active = getattr(self, "_active_sessions", None)
+            tasks = getattr(self, "_session_tasks", None)
+            pending = getattr(self, "_pending_messages", None)
+            store_fn = getattr(self, "_text_debounce_store", None)
+            runner = getattr(self, "gateway_runner", None)
+            peek = getattr(runner, "_peek_session_state", None)
+            if (
+                not isinstance(active, dict) or not isinstance(tasks, dict) or not isinstance(pending, dict)
+                or not callable(store_fn) or not callable(peek)
+            ):
+                self._warn_idle_inputs_missing()
+                return False
+            if session_key in pending:
+                return False
+            store = store_fn()
+            if not isinstance(store, dict) or session_key in store:
+                return False
+            task = tasks.get(session_key)
+            if task is not None and task is not completing and not task.done():
+                return False
+            if session_key in active and task is None:
+                return False  # a guard with no owner task: a command is running
+            for key in {session_key, *(k for k in runner_keys if k)}:
+                state = peek(key)
+                if state is None:
+                    continue
+                if state.turn.agent is not None:
+                    return False
+                if state.conversation.queued_events:
+                    return False
+            return True
+        except Exception:
+            return False
+
+    def _release_if_idle(self, session_key: Optional[str], completing: Any, runner_key: Optional[str] = None) -> None:
+        """Release every count attached to this session once it is idle."""
+        if session_key is None:
+            return
+        waiting = _ATTACHED.get(session_key)
+        if not waiting:
+            return
+        runner_keys = tuple(rk for _, rk in waiting) + (runner_key,)
+        if self._session_idle(session_key, completing, runner_keys):
+            for token, _ in _ATTACHED.pop(session_key, []):
+                _TURN_AUTHZ.end_ungranted(*token)
+
+    def _settle_on_completion(self, event: Any) -> None:
+        """H0.2 (d)+(e): at every completion in a session, release what is
+        attached to it if the session is idle."""
+        self._release_if_idle(self._session_key_of(event), asyncio.current_task(), self._runner_key_of(event))
+
     async def _await_acceptance(self, event: Any) -> str:
         """"accepted" once Hermes holds the turn durably (marker persisted) or
         has finished it; "cancelled" when Hermes cancelled it before that
@@ -834,6 +977,10 @@ class SecureComsAdapter(BasePlatformAdapter):
         # (Hermes keys group sessions per user), never a DM: guessing DM would
         # put a room's messages into a direct-chat session.
         chat_type = "dm" if meta.get("is_dm") is True else "group"
+        if securecoms_authz.block_says_dm(frame):
+            # Audit r2: the daemon's block marks a DM whatever this cache says
+            # (a cache miss or a failed refresh must not skip the H0.2c split).
+            chat_type = "dm"
 
         global _FRAMES_WITHOUT_AUTHORIZATION, _ATTACHMENTS_DROPPED
         if not isinstance(frame.get("authorization"), dict):
@@ -845,7 +992,20 @@ class SecureComsAdapter(BasePlatformAdapter):
                     "Upgrade @securecoms/agent-bridge"
                 )
         tools_allowed = securecoms_authz.tools_allowed(frame)
-        _TURN_AUTHZ.record(channel_id, sender_id, tools_allowed)
+        if tools_allowed and self._room_sessions_shared and chat_type != "dm":
+            tools_allowed = False  # H0.2b: one room session for every sender
+        # H0.2c: Hermes keys a DM session by chat only. Every non-owner DM turn
+        # runs in its own session (thread NON_OWNER_THREAD), so its text never
+        # enters the transcript the owner's granted turns run in.
+        thread_id = None
+        if chat_type == "dm":
+            thread_id = securecoms_authz.dm_thread(frame)
+        if thread_id is not None:
+            # Defence in depth only: no non-owner or unclassified frame passes
+            # securecoms_authz.tools_allowed, and the ledger forces these
+            # threads off. Removing this line is an equivalent mutant (N4).
+            tools_allowed = False
+        _TURN_AUTHZ.record(channel_id, sender_id, tools_allowed, thread_id)
         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 at once by
@@ -856,11 +1016,25 @@ class SecureComsAdapter(BasePlatformAdapter):
 
         source = self.build_source(
             chat_id=channel_id,
-            chat_name=meta.get("name", channel_id),
+            # The room name is member-chosen and reaches the prompt: same
+            # sanitizer as the sender label, falling back to the channel id.
+            chat_name=securecoms_transport.display_name(meta.get("name")) or channel_id,
             chat_type=chat_type,
+            # user_id (Hermes's session and the tool ledger key) is the
+            # relay-attributed sender_id; user_name is a sanitized label of
+            # that same sender (R3). thread_id: H0.2c above.
             user_id=sender_id,
-            user_name=sender_id,
+            thread_id=thread_id,
+            user_name=securecoms_transport.own_label(frame),
         )
+        speaker = securecoms_transport.speaker_label(frame)
+        if speaker and isinstance(text, str):
+            # A relayed voice room: one Hermes session (the relay's) holds
+            # several speakers, and Hermes pins user_name in the per-session
+            # system prompt, so the real speaker rides each turn's text, the
+            # way Hermes's own shared sessions prefix "[sender name]". The
+            # label's name part cannot contain "[]()" (R3, M2).
+            text = f"[{speaker}] {text}"
         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:
@@ -909,10 +1083,51 @@ class SecureComsAdapter(BasePlatformAdapter):
         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)
-        event._securecoms_session_was_busy = self._session_was_busy(event)
-        await self.handle_message(event)
+        token = None
+        session_key = None
+        if not tools_allowed:
+            # H0.2 (a): this key has no tools until no turn in its session can
+            # still be processing this event's text. Attached to the session
+            # now; released only when the session is idle.
+            token = (channel_id, sender_id, thread_id, self._room_sessions_shared and chat_type != "dm")
+            _TURN_AUTHZ.begin_ungranted(*token)
+            session_key = self._session_key_of(event)
+            if session_key is None:
+                logger.warning(
+                    "SecureComs: an ungranted turn's Hermes session is unknown; its sender stays without tools"
+                )
+            else:
+                _ATTACHED.setdefault(session_key, []).append((token, self._runner_key_of(event)))
+        reached = False
+        try:
+            event._securecoms_session_was_busy = self._session_was_busy(event)
+            reached = True
+            await self.handle_message(event)
+        except BaseException:
+            if token is not None and not reached:
+                self._detach(session_key, token)  # never reached Hermes
+                _TURN_AUTHZ.end_ungranted(*token)
+            elif token is not None:
+                self._release_if_idle(session_key, None)
+            raise
+        if token is not None:
+            # (b)/(c): released now only if nothing in the session can still
+            # be processing it; else at a later idle completion (d)/(e).
+            self._release_if_idle(session_key, None)
         return event
 
+    @staticmethod
+    def _detach(session_key: Optional[str], token: tuple) -> None:
+        waiting = _ATTACHED.get(session_key) if session_key is not None else None
+        if not waiting:
+            return
+        for i, (t, _) in enumerate(waiting):
+            if t is token:
+                del waiting[i]
+                break
+        if not waiting:
+            _ATTACHED.pop(session_key, None)
+
     def _may_look_up(self, channel_id: str) -> bool:
         """Negative cache for unknown channels: True at most once per
         _UNKNOWN_CHANNEL_RETRY_S per channel (bounded map, oldest evicted)."""
@@ -945,12 +1160,14 @@ class SecureComsAdapter(BasePlatformAdapter):
     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."""
+        toolsets: only for a (chat, sender, thread) whose latest turn was
+        granted tools and that has no ungranted turn still in flight (H0).
+        Anything else, including an unknown source and every turn in the
+        non-owner DM thread, 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):
+        thread_id = getattr(source, "thread_id", None)
+        if _TURN_AUTHZ.tools_allowed(chat_id, user_id, thread_id):
             return None
         return list(securecoms_authz.NO_TOOLS_TOOLSETS)
 
@@ -1097,7 +1314,21 @@ def _install_tool_veto(ctx) -> bool:
         ):
             return False
         from gateway import session_context
-        from gateway.session_context import get_session_env
+
+        # Read the turn's task-local ContextVars directly: Hermes's own
+        # get_session_env falls back to os.environ, which a concurrent turn or
+        # the process can set. Unset (_UNSET) reads as None, never as a value.
+        var_map = getattr(session_context, "_VAR_MAP", None)
+        unset = getattr(session_context, "_UNSET", None)
+        names = ("HERMES_SESSION_PLATFORM", "HERMES_SESSION_CHAT_ID", "HERMES_SESSION_USER_ID", "HERMES_SESSION_THREAD_ID")
+        if unset is None or not isinstance(var_map, dict) or not all(
+            callable(getattr(var_map.get(n), "get", None)) for n in names
+        ):
+            return False
+
+        def get_session_env(name, default=""):
+            value = var_map[name].get()
+            return None if value is unset else value
 
         engaged = getattr(session_context, "session_context_engaged", None)
         _SESSION_ENGAGED = engaged if callable(engaged) else None

package/connectors/hermes/securecoms_authz.py

@@ -113,6 +113,56 @@ def tools_allowed(frame: Any) -> bool:
     return all(_is_grant(g) for g in grants)
 
 
+# H0.2c (re-ruled after code audit r1): Hermes keys a DM session by chat only,
+# so every non-owner DM turn (a guest's relayed voice, any other sender, a frame
+# with no valid block) runs in its own Hermes session, selected by this
+# thread id. No ":" (Hermes joins session-key parts with ":"). A ledger record
+# under this thread is never a grant.
+NON_OWNER_THREAD = "sc-non-owner"
+# Audit r2 (ruled): a DM frame whose block cannot be classified (missing,
+# malformed, wrong version, or sender_membership not "active", e.g. the owner
+# during a stale roster) runs in a THIRD session, never the owner's and never
+# the guests'. Forced ungranted like NON_OWNER_THREAD.
+UNCLASSIFIED_THREAD = "sc-unclassified"
+_FORCED_OFF_THREADS = (NON_OWNER_THREAD, UNCLASSIFIED_THREAD)
+# authorizationFor (bridge-agent.ts:9093-9094) sets these audiences only when
+# the channel is a DM, and sets relay_speaker only inside its is_dm branch.
+_DM_AUDIENCES = ("owner_dm", "other_human_dm")
+
+
+def is_owner_turn(frame: Any) -> bool:
+    """True only for a valid block with ``audience == "owner_dm"`` or the
+    daemon's ``relay_speaker: "owner"`` mark (granted or not). Anything else,
+    including no block or a malformed one, is a non-owner turn."""
+    block = _valid_block(frame)
+    if block is None:
+        return False
+    return block.get("audience") == "owner_dm" or block.get("relay_speaker") == "owner"
+
+
+def dm_thread(frame: Any) -> Optional[str]:
+    """The Hermes thread for a DM turn: None for an owner turn (owner session),
+    UNCLASSIFIED_THREAD when the block cannot be classified, else
+    NON_OWNER_THREAD."""
+    if _valid_block(frame) is None:
+        return UNCLASSIFIED_THREAD
+    return None if is_owner_turn(frame) else NON_OWNER_THREAD
+
+
+def block_says_dm(frame: Any) -> bool:
+    """True when the daemon's block marks this turn as a DM turn (a DM
+    audience or any relay_speaker mark). Read from the raw block, valid or
+    not: it only ever moves a turn OUT of a shared session, never grants."""
+    block = frame.get("authorization") if isinstance(frame, dict) else None
+    if not isinstance(block, dict):
+        return False
+    return block.get("audience") in _DM_AUDIENCES or "relay_speaker" in block
+
+
+def _thread_key(thread_id: Any) -> Any:
+    return "" if thread_id is None else thread_id
+
+
 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:
@@ -124,12 +174,24 @@ def sender_role(frame: Any) -> str:
 
 
 class TurnAuthzLedger:
-    """The tool decision of the latest inbound frame per (chat_id, sender).
+    """The tool decision of the latest inbound frame per (chat_id, sender,
+    thread), held down by any ungranted turn for that key still in flight.
 
     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.
+    dispatch and looked up when a tool is about to run (by the chat, user and
+    thread Hermes binds to that turn's session). Unrecorded or evicted keys
+    have no tools. A record under NON_OWNER_THREAD or UNCLASSIFIED_THREAD is
+    always "no tools".
+
+    H0 (audit r1 #3, r2 #1): the latest decision alone let a guest's turn that
+    was still running borrow a grant recorded later for the same key. An
+    ungranted event therefore holds an in-flight count (begin_ungranted /
+    end_ungranted) until no turn in its Hermes session can still be processing
+    its text; while the count is above zero the key has no tools, whatever the
+    latest decision says. A ``shared_session`` count (H0.2b: a room whose
+    Hermes session is shared by every sender) blocks every key in that chat.
+    The counts are never evicted (dropping one would fail open) and a grant
+    never lowers them.
     """
 
     def __init__(self, max_entries: int = 4096):
@@ -139,13 +201,42 @@ class TurnAuthzLedger:
         # 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()
+        # In-flight ungranted events per (chat_id, user_id, thread), and per
+        # chat for shared room sessions. Never evicted by max_entries.
+        self._inflight: Dict[tuple, int] = {}
+        self._inflight_chat: Dict[Any, int] = {}
+
+    def begin_ungranted(self, chat_id: Any, user_id: Any, thread_id: Any = None, shared_session: bool = False) -> None:
+        key = (chat_id, user_id, _thread_key(thread_id))
+        if isinstance(chat_id, str) and chat_id:
+            self._chats.add(chat_id)
+        self._inflight[key] = self._inflight.get(key, 0) + 1
+        if shared_session:
+            self._inflight_chat[chat_id] = self._inflight_chat.get(chat_id, 0) + 1
+
+    def end_ungranted(self, chat_id: Any, user_id: Any, thread_id: Any = None, shared_session: bool = False) -> None:
+        key = (chat_id, user_id, _thread_key(thread_id))
+        n = self._inflight.get(key, 0)
+        if n <= 1:
+            self._inflight.pop(key, None)
+        else:
+            self._inflight[key] = n - 1
+        if shared_session:
+            c = self._inflight_chat.get(chat_id, 0)
+            if c <= 1:
+                self._inflight_chat.pop(chat_id, None)
+            else:
+                self._inflight_chat[chat_id] = c - 1
 
-    def record(self, chat_id: Any, user_id: Any, allowed: bool) -> None:
-        key = (chat_id, user_id)
+    def ungranted_in_flight(self, chat_id: Any, user_id: Any, thread_id: Any = None) -> int:
+        return self._inflight.get((chat_id, user_id, _thread_key(thread_id)), 0)
+
+    def record(self, chat_id: Any, user_id: Any, allowed: bool, thread_id: Any = None) -> None:
+        key = (chat_id, user_id, _thread_key(thread_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
+        self._entries[key] = allowed is True and thread_id not in _FORCED_OFF_THREADS
         while len(self._entries) > self._max:
             self._entries.popitem(last=False)
 
@@ -155,10 +246,15 @@ class TurnAuthzLedger:
             return False
         return chat_id in self._chats
 
-    def tools_allowed(self, chat_id: Any, user_id: Any) -> bool:
+    def tools_allowed(self, chat_id: Any, user_id: Any, thread_id: Any = None) -> 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
+        if thread_id is not None and not isinstance(thread_id, str):
+            return False
+        key = (chat_id, user_id, _thread_key(thread_id))
+        if self._inflight.get(key, 0) > 0 or self._inflight_chat.get(chat_id, 0) > 0:
+            return False
+        return self._entries.get(key) is True
 
 
 def pre_tool_call_decision(
@@ -180,14 +276,19 @@ def pre_tool_call_decision(
       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.
+    A failure to read the session blocks. ``get_session_env(name, default)``
+    returns the turn's task-local value, or None when the variable is unset in
+    this task (no environment fallback): an unset or empty chat or user, or an
+    unset thread, blocks a SecureComs turn. The thread is "" for an owner turn.
     """
     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", "")
+        thread_id = get_session_env("HERMES_SESSION_THREAD_ID", "")
+        platform = "" if platform is None else platform
         if platform == PLATFORM_ID or ledger.knows_chat(chat_id):
-            if ledger.tools_allowed(chat_id, user_id):
+            if isinstance(thread_id, str) and ledger.tools_allowed(chat_id, user_id, thread_id or None):
                 return None
         elif platform == "":
             engaged = True if session_engaged is None else session_engaged() is not False

package/connectors/hermes/securecoms_transport.py

@@ -28,6 +28,7 @@ import json
 import os
 import re
 import stat
+import unicodedata
 from typing import Awaitable, Callable, List, Mapping, NamedTuple, Optional, Tuple
 
 from securecoms_gate import evaluate_gate, resolve_bound_identity
@@ -198,6 +199,114 @@ def should_drop_inbound(frame: dict, bound_identity: str) -> bool:
     return bool(sender_id) and bool(bound_identity) and sender_id == bound_identity
 
 
+# Display names (R3). sender_name, a relayed voice turn's speaker name and a
+# room name are member-chosen strings that reach the LLM prompt, so they must
+# not be able to start a new line or fake prompt structure. Python twin of
+# openclaw-entry.js's displayName/senderLabel; both are pinned to the same
+# cases by ../display-name-fixtures.json. Residual drift: character
+# categories come from each runtime's Unicode tables (Python unicodedata vs
+# the JS engine's ICU), so a character assigned in a newer Unicode version
+# can be "unassigned, dropped" in one runtime and kept in the other.
+# A label only: identity, sessions and authorization stay on sender_id and the
+# daemon's authorization block.
+DISPLAY_NAME_MAX = 64
+# These C0/C1 controls become a space (as Python isspace and JS \s do); every
+# other C* character is dropped; every Z* character becomes a space.
+_NAME_SPACE_CONTROLS = frozenset("\t\n\v\f\r\x1c\x1d\x1e\x1f\x85")
+# Letters (Lo/So) that render as nothing: Hangul fillers and the blank braille
+# pattern. Dropped so a blank-looking name falls back to the id.
+_INVISIBLE_LETTERS = frozenset("\u115f\u1160\u3164\uffa0\u2800")
+# Stripped from the NAME part of a label, after NFKC folds compatibility
+# lookalikes (fullwidth, small, superscript forms) to their ASCII originals:
+# every opening/closing/initial/final punctuation character (Ps/Pe/Pi/Pf, so
+# any bracket or quote Unicode classifies as one) plus "<>|" and the backtick.
+# That keeps a name from faking the trusted " (owner)" / " (<id>)" suffix, a
+# "[name]" turn prefix, a tag or a table cell with any bracket Unicode
+# classifies as such. A glyph that merely looks like a bracket but is
+# classified otherwise (e.g. a letter or symbol) is not caught.
+_LABEL_STRUCTURE = frozenset("<>|`")
+_LABEL_STRUCTURE_CATEGORIES = frozenset(("Ps", "Pe", "Pi", "Pf"))
+LABEL_ID_CHARS = 8
+
+
+def display_name(raw: object) -> str:
+    """Whitespace (newlines, tabs, Unicode line/paragraph separators) becomes
+    one space; other control, format (bidi, zero-width), surrogate,
+    private-use and unassigned characters and invisible fillers are dropped;
+    runs of spaces collapse; the result is trimmed and capped at
+    DISPLAY_NAME_MAX code points. "" for a non-string or nothing left."""
+    if not isinstance(raw, str):
+        return ""
+    out = []
+    for ch in raw:
+        cat = unicodedata.category(ch)
+        if ch in _NAME_SPACE_CONTROLS or cat[0] == "Z":
+            out.append(" ")
+        elif cat[0] != "C" and ch not in _INVISIBLE_LETTERS:
+            out.append(ch)
+    return " ".join("".join(out).split())[:DISPLAY_NAME_MAX].rstrip()
+
+
+def _label_name(raw: object) -> str:
+    if not isinstance(raw, str):
+        return ""
+    folded = unicodedata.normalize("NFKC", raw)
+    return display_name("".join(
+        ch for ch in folded
+        if ch not in _LABEL_STRUCTURE and unicodedata.category(ch) not in _LABEL_STRUCTURE_CATEGORIES))
+
+
+def _valid_authorization(frame: Mapping) -> Optional[Mapping]:
+    """The daemon's v1 block for an active sender (securecoms_authz's rule)."""
+    block = frame.get("authorization")
+    if not isinstance(block, dict):
+        return None
+    version = block.get("version")
+    if version != 1 or isinstance(version, bool) or block.get("sender_membership") != "active":
+        return None
+    return block
+
+
+def _label(raw_name: object, raw_id: object, is_owner: bool) -> str:
+    """name + a suffix built only from trusted data: " (owner)" when the
+    daemon's block says so, else " (<first LABEL_ID_CHARS of the id>)". No
+    usable name: the id itself (plus " (owner)" for the owner)."""
+    name = _label_name(raw_name)
+    ident = _label_name(raw_id)
+    if name:
+        return f"{name} ({'owner' if is_owner else (ident[:LABEL_ID_CHARS] or 'unknown')})"
+    if ident and is_owner:
+        return f"{ident} (owner)"
+    return ident
+
+
+def own_label(frame: Mapping) -> str:
+    """The frame sender's label (the relay itself on a relayed voice turn).
+    Owner only on the daemon's owner_dm block."""
+    block = _valid_authorization(frame)
+    is_owner = block is not None and block.get("audience") == "owner_dm"
+    return _label(frame.get("sender_name"), frame.get("sender_id"), is_owner)
+
+
+def speaker_label(frame: Mapping) -> str:
+    """A relayed voice turn's speaker label, or "" when the frame has no
+    speaker with a usable identityId. Owner only on the daemon's
+    relay_speaker="owner" mark (never on what the speaker claims)."""
+    speaker = frame.get("speaker")
+    if not isinstance(speaker, dict) or not _label_name(speaker.get("identityId")):
+        return ""
+    block = _valid_authorization(frame)
+    is_owner = block is not None and block.get("relay_speaker") == "owner"
+    return _label(speaker.get("displayName"), speaker.get("identityId"), is_owner)
+
+
+def sender_label(frame: Mapping) -> str:
+    """Who the model is told spoke this turn: the relayed speaker when there
+    is one, else the sender. Display data only, never an authorization or
+    session input."""
+    return speaker_label(frame) or own_label(frame)
+
+
 # Inbound attachments. For an artifact_share the daemon decrypts the file to
 # <attachmentsDir>/<channel_id>/<message_id>-<name> and puts
 # {filename, mime, size, path, sha256} on the frame. Python twin of