@securecoms/agent-bridge 0.37.0 → 0.38.0

package/README.md

@@ -973,6 +973,22 @@ copied after the owner's next typed message.
 
 ---
 
+## Release notes: 0.38.0
+
+<!-- [COPY, released on Eric's "complete all three items" 2026-11-11; notes not yet reviewed by Eric] -->
+
+#### What's new
+- **Your agent sees your pictures.** When you send a picture, your agent can now see it and describe it. This works for OpenClaw, Hermes and SecureComs agents. It works for PNG, JPEG, GIF and WebP pictures up to 5 MB.
+- **A picture and its caption are one message.** When you send a picture with a caption, your agent gets them together and answers once.
+- **Safer pictures.** Your agent reads a picture only when the file really is the picture type it claims to be. In a team room, a picture follows the same @mention rules as a text message. The pictures are kept in private folders that only your account can read.
+- **Hermes keeps your messages.** If Hermes stops in the middle of a reply, it now picks up your message again when it restarts, in almost all cases. You can still send `/stop` while Hermes is working.
+
+#### Upgrade
+
+Upgrade the bridge and restart your agent. For a SecureComs agent, also upgrade to @securecoms/agent-runtime 0.18.0. For OpenClaw or Hermes, copy the new plugin files from the bridge's `connectors` folder.
+
+If you go back to 0.37.0, your agent keeps working, but it sees each picture and its caption as two messages.
+
 ## Release notes: 0.37.0
 
 <!-- [COPY, approved by Eric 2026-11-01 ("Notes ok"), connected apps removal confirmation] -->

package/connectors/hermes/adapter.py

@@ -13,6 +13,9 @@ Flow:
               -->  Hermes gateway  -->  LLM  -->  send()  -->  daemon  --MLS-->  owner
     outbound: the agent's reply is delivered to send(), which POSTs it to the
               daemon's /v1/send; the daemon encrypts and relays it.
+    ack:      an inbound frame is acked to the daemon once Hermes has durably
+              accepted its turn (see _receive_message); after that, crash
+              recovery is Hermes's own (its persisted active-turn marker).
 
 This is the universal daemon-client pattern wearing a Hermes BasePlatformAdapter
 shim. The same daemon serves any framework; only this thin shim is
@@ -60,6 +63,7 @@ import json
 import logging
 import os
 import time
+from collections import OrderedDict
 from datetime import datetime
 from typing import Any, Dict, Optional
 
@@ -108,6 +112,46 @@ _REFUSAL_NOTICE_SENT: set = set()
 _REFUSAL_NOTICE_MAX = 4096
 # Inbound frames seen without an authorization block (daemon too old).
 _FRAMES_WITHOUT_AUTHORIZATION = 0
+# Inbound attachments dropped by securecoms_transport.scan_inbound_attachments.
+_ATTACHMENTS_DROPPED = 0
+# Unknown-channel lookups (review r2): one /v1/channels refresh per unknown
+# channel per minute, each bounded so a slow daemon cannot stall a turn.
+_UNKNOWN_CHANNEL_RETRY_S = 60.0
+_UNKNOWN_CHANNEL_LOOKUPS_MAX = 4096
+_CHANNEL_REFRESH_TIMEOUT_S = 5.0
+
+# Ack on durable acceptance (see _receive_message). Hermes's handle_message
+# returns as soon as it has spawned the turn as a background task, so an ack
+# sent when it returned could reach the daemon before Hermes held the message
+# anywhere durable: a crash then lost it (the daemon never redelivers an acked
+# row). Acking after the WHOLE turn is wrong too: the daemon delivers one
+# message per channel and the next only after the ack (ws-server.ts F2), which
+# would hold back /stop, /approve and clarify answers until the turn ended, and
+# Hermes already resumes a crashed turn from its own durable marker, so a
+# daemon redelivery on top would run it twice. So the ack goes out once Hermes
+# has persisted its active-turn marker for this event, or finished with it.
+# Redeliveries are deduped by message_id in a bounded ledger.
+_DEDUP_MAX_ENTRIES = 2048
+_DEDUP_TTL_S = 600.0
+# How long to wait for Hermes to accept a turn that starts its own session
+# task before acking anyway (holding the ack holds the channel, F2).
+_ACCEPT_WAIT_S = 10.0
+_ACCEPT_POLL_S = 0.02
+# One warning per process when this Hermes lacks the acceptance signal.
+_TURN_TRACKING_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"))
+
+
+def _message_type_for_mimes(mimes):
+    name = next(
+        (n for prefix, n in _MEDIA_TYPE_BY_MIME_PREFIX if any(m.startswith(prefix) for m in mimes)),
+        "DOCUMENT",
+    )
+    return getattr(MessageType, name, MessageType.TEXT)
+
 
 _PLUGIN_DIR = os.path.dirname(os.path.abspath(__file__))
 _BINDING_PATH = os.path.join(_PLUGIN_DIR, "securecoms.binding.json")
@@ -146,6 +190,69 @@ def _error_class(error: object) -> str:
     return name
 
 
+class _DeliveryLedger:
+    """Bounded record of inbound message_ids that are in flight or done.
+
+    begin() answers "new" (record it in flight and dispatch), "in_flight" (a
+    redelivery of a turn still running: do not dispatch, the original's ack
+    covers it) or "done" (already finished: ack again, no turn). An in-flight
+    entry is never evicted or expired, since dropping it would let a
+    redelivery run the turn twice; the daemon keeps at most one message per
+    channel in flight, so those stay few. Done entries expire after ttl_s and
+    the oldest go first once the ledger holds more than max_entries, except
+    pinned ones (acked by us but never delivered to the daemon).
+    """
+
+    def __init__(self, max_entries: int, ttl_s: float, now) -> None:
+        self._max = max_entries
+        self._ttl = ttl_s
+        self._now = now
+        # message_id -> monotonic finish time, or None while in flight.
+        self._entries: "OrderedDict[str, Optional[float]]" = OrderedDict()
+        # Done ids whose ack never reached the daemon: kept past TTL and LRU,
+        # so a redelivery after a long outage is acked, never re-run.
+        self._pinned: set = set()
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    def begin(self, message_id: str) -> str:
+        self._prune()
+        if message_id in self._entries:
+            return "in_flight" if self._entries[message_id] is None else "done"
+        self._entries[message_id] = None
+        return "new"
+
+    def finish(self, message_id: str) -> None:
+        self._entries.pop(message_id, None)
+        self._entries[message_id] = self._now()
+        self._prune()
+
+    def forget(self, message_id: str) -> None:
+        self._entries.pop(message_id, None)
+        self._pinned.discard(message_id)
+
+    def pin(self, message_id: str) -> None:
+        if message_id in self._entries:
+            self._pinned.add(message_id)
+
+    def unpin(self, message_id: str) -> None:
+        self._pinned.discard(message_id)
+
+    def _prune(self) -> None:
+        now = self._now()
+        excess = len(self._entries) - self._max
+        for mid, done_at in list(self._entries.items()):
+            if done_at is None or mid in self._pinned:
+                continue
+            if now - done_at > self._ttl:
+                del self._entries[mid]
+                excess -= 1
+            elif excess > 0:
+                del self._entries[mid]
+                excess -= 1
+
+
 def _read_file_text(path: str) -> str:
     with open(path, "r") as f:
         return f.read()
@@ -180,11 +287,20 @@ class SecureComsAdapter(BasePlatformAdapter):
         # SEC-06 #18: reply_to -> {"seq": n, "pending": text|None}; see _block_key.
         self._block_seq: Dict[str, Dict[str, Any]] = {}
         self._session = None  # aiohttp.ClientSession - the CURRENT connected link
+        # channel_id -> monotonic time of the last lookup for an unknown channel.
+        self._unknown_channel_lookups: Dict[str, float] = {}
         self._ws = None
         self._recv_task: Optional[asyncio.Task] = None
         self._tick_task: Optional[asyncio.Task] = None
         self._stopped = False  # set by disconnect(); stops the reconnect supervisor
         self._hold_reason: Optional[str] = None  # None == not holding
+        # Inbound message_ids awaiting their ack or acked, and the tasks that
+        # each wait for Hermes to accept one turn and then send its ack.
+        self._deliveries = _DeliveryLedger(_DEDUP_MAX_ENTRIES, _DEDUP_TTL_S, time.monotonic)
+        self._ack_waiters: set = set()
+        # message_ids whose ack was dropped (no link, or the send raised), in
+        # order; flushed on the next successful connect.
+        self._unsent_acks: "OrderedDict[str, None]" = OrderedDict()
 
         self._status = securecoms_transport.ChannelStatusManager(
             self._send_status_frame, now=time.monotonic
@@ -291,6 +407,7 @@ class SecureComsAdapter(BasePlatformAdapter):
         self._token = target.token
         self._leave_hold()
         await self._send_hello()
+        await self._flush_unsent_acks()
         await self._refresh_channels()
         return True
 
@@ -389,19 +506,31 @@ class SecureComsAdapter(BasePlatformAdapter):
                     await task
                 except asyncio.CancelledError:
                     pass
+        # Unsent acks are dropped on purpose: the daemon re-buffers whatever is
+        # unacked when the socket closes and redelivers it to the next consumer.
+        waiters = list(self._ack_waiters)
+        for task in waiters:
+            task.cancel()
+        if waiters:
+            await asyncio.gather(*waiters, return_exceptions=True)
+        self._ack_waiters.clear()
         await self._teardown_link()
 
+    async def _fetch_channels(self) -> None:
+        async with self._session.get(
+            f"{self.bridge_url}/v1/channels", headers=self._auth()
+        ) as r:
+            if r.status == 200:
+                for c in await r.json():
+                    self._channels[c["channel_id"]] = {
+                        "name": c.get("name") or c["channel_id"],
+                        "is_dm": bool(c.get("is_dm")),
+                    }
+
     async def _refresh_channels(self) -> None:
         try:
-            async with self._session.get(
-                f"{self.bridge_url}/v1/channels", headers=self._auth()
-            ) as r:
-                if r.status == 200:
-                    for c in await r.json():
-                        self._channels[c["channel_id"]] = {
-                            "name": c.get("name") or c["channel_id"],
-                            "is_dm": bool(c.get("is_dm")),
-                        }
+            # Bounded: an inbound turn may wait on this (review r2).
+            await asyncio.wait_for(self._fetch_channels(), timeout=_CHANNEL_REFRESH_TIMEOUT_S)
         except Exception as e:
             logger.debug(
                 "SecureComs: channel refresh failed (error_class=%s)",
@@ -452,34 +581,261 @@ class SecureComsAdapter(BasePlatformAdapter):
                 except (ValueError, TypeError):
                     continue
                 if frame.get("type") == "message":
-                    await self._dispatch(frame)
-                    # at-least-once: ack every accepted frame, dropped or not
-                    # (echo-guard drops still need the daemon to stop
-                    # redelivering them).
-                    try:
-                        await self._ws.send_json(
-                            {"type": "ack", "message_id": frame.get("message_id")}
-                        )
-                    except Exception as e:
-                        logger.warning(
-                            "SecureComs: ack failed (error_class=%s)",
-                            _error_class(e),
-                        )
+                    await self._receive_message(frame)
             elif msg.type in (aiohttp.WSMsgType.CLOSED, aiohttp.WSMsgType.ERROR):
                 return  # WS closed → supervisor reconnects
 
-    async def _dispatch(self, frame: Dict[str, Any]) -> None:
-        if not self._message_handler:
+    async def _receive_message(self, frame: Dict[str, Any]) -> None:
+        """At-least-once intake for one `message` frame.
+
+        Ack timing:
+          - dropped before Hermes (echo guard, refused ungranted turn, no
+            handler): at once, as before, so the daemon stops redelivering;
+          - handled inline by Hermes, queued behind a busy session, or not
+            queued for a turn (a /stop, an /approve, a clarify answer, a
+            follow-up, a steer, a queue-mode debounce): at once;
+          - starting its own Hermes turn: once Hermes has durably accepted
+            it (_await_acceptance), at most _ACCEPT_WAIT_S later.
+        The wait runs in its own task, so this pump keeps reading and other
+        channels keep flowing; handle_message is still called here, in frame
+        order. A redelivery of an id still waiting is not dispatched (the
+        original's ack covers it); one already acked is acked again with no
+        turn. A frame without a message_id is not deduped (unchanged).
+        """
+        mid = frame.get("message_id")
+        key = mid if isinstance(mid, str) and mid else None
+        if key is not None:
+            state = self._deliveries.begin(key)
+            if state == "done":
+                await self._send_ack(mid)
+                return
+            if state == "in_flight":
+                return
+        try:
+            event = await self._dispatch(frame)
+        except BaseException:
+            # Unacked, exactly as before: the supervisor reconnects and the
+            # daemon redelivers, which must then run the turn again.
+            if key is not None:
+                self._deliveries.forget(key)
+            raise
+        if event is None or not self._awaits_acceptance(event):
+            if key is not None:
+                self._deliveries.finish(key)
+            await self._send_ack(mid)
             return
+        task = asyncio.create_task(self._ack_on_acceptance(mid, key, event))
+        self._ack_waiters.add(task)
+        task.add_done_callback(self._ack_waiters.discard)
+
+    # Hermes internals this relies on (v2026.9.24), all read-only:
+    #   - MessageEvent._gateway_accepted: reset to False on entry to
+    #     handle_message (gateway/platforms/base.py:3953), True when the event
+    #     starts a session task (:3990) or is queued for one (:4052, :4064,
+    #     gateway/run_busy.py:88-97 _enqueue_fifo).
+    #   - _event_session_key / _active_sessions / _session_tasks: read before
+    #     handle_message to tell "starts its own turn" from "queued behind a
+    #     busy session" (base.py:2488, 1924, 1928, 3983-3987).
+    #   - MessageEvent._gateway_active_turn_token: set by the runner's
+    #     _mark_durable_active_turn (gateway/run_inbound.py:1754-1767) only
+    #     after SessionStore.mark_turn_active has persisted the marker
+    #     (gateway/session_lifecycle.py:115-145, write before publish), at
+    #     gateway/run_turn.py:2090. An unclean restart promotes the marker to
+    #     resume_pending (session_lifecycle.py:156-185) and resumes the
+    #     session (gateway/run_startup.py:575-620).
+    #   - on_processing_complete(event, outcome): called on every exit of
+    #     _process_message_background (base.py:4520-4540).
+    # Without _gateway_accepted this degrades to acking at dispatch, the old
+    # behaviour, with one warning.
+    #
+    # Accepted gaps (each no worse than acking at dispatch, as main does):
+    #   - The marker is written at run_turn.py:2090, but the user's message
+    #     reaches the transcript only in _persist_turn_start just before the
+    #     first LLM call (agent/turn_context.py:963, called at :1152). In
+    #     between: the transcript load, _hmwa_run_session_hygiene (which can
+    #     make a compression LLM call, run_turn.py:1346) and the agent build.
+    #     A crash there resumes the session with an empty-text event
+    #     (run_startup.py:610) and the acked message is lost.
+    #   - A clean shutdown while the session's agent is still
+    #     _AGENT_PENDING_SENTINEL (before the agent build) does not mark it
+    #     resume_pending (gateway/run_shutdown.py:858-871), and a clean start
+    #     discards orphan markers (session_lifecycle.py:189): acked, then lost.
+    #   - A follow-up queued behind a busy session, a queue-mode debounce
+    #     (base.py:3766-3796) or a steer is acked at once: Hermes holds it
+    #     only in memory until its own turn starts (its pending queue is saved
+    #     on clean shutdown only).
+
+    def _awaits_acceptance(self, event: Any) -> bool:
+        accepted = getattr(event, "_gateway_accepted", None)
+        if not isinstance(accepted, bool):
+            self._warn_no_turn_tracking()
+            return False
+        # Queued behind a busy session: not durable until its own turn
+        # starts, which may be minutes away, so waiting buys nothing and
+        # would hold the channel (a /stop typed next would wait the bound).
+        return accepted and not getattr(event, "_securecoms_session_was_busy", False)
+
+    def _session_was_busy(self, event: Any) -> bool:
+        """Read BEFORE handle_message: does this event's Hermes session
+        already have a live owner? Mirrors handle_message's own check
+        (base.py:3983-3987): a guard in _active_sessions whose owner task in
+        _session_tasks has not exited (a done owner is healed on entry)."""
+        key_fn = getattr(self, "_event_session_key", None)
+        active = getattr(self, "_active_sessions", None)
+        if not callable(key_fn) or not isinstance(active, dict):
+            return False
+        try:
+            key = key_fn(event)
+        except Exception:
+            return False
+        if key not in active:
+            return False
+        tasks = getattr(self, "_session_tasks", None)
+        task = tasks.get(key) if isinstance(tasks, dict) else None
+        done = getattr(task, "done", None)
+        return not (callable(done) and done())
+
+    @staticmethod
+    def _warn_no_turn_tracking() -> None:
+        global _TURN_TRACKING_WARNED
+        if _TURN_TRACKING_WARNED:
+            return
+        _TURN_TRACKING_WARNED = True
+        logger.warning(
+            "SecureComs: Hermes turn acceptance signal unavailable; acking at dispatch "
+            "(a crash before the turn starts can lose that message)"
+        )
+
+    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."""
+        try:
+            event._securecoms_outcome = getattr(outcome, "name", None) or "UNKNOWN"
+        except Exception:
+            pass
+        base = getattr(super(), "on_processing_complete", None)
+        if callable(base):
+            await base(event, outcome)
+
+    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
+        (gateway shutdown: cancel_background_tasks); "timeout" after
+        _ACCEPT_WAIT_S."""
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + _ACCEPT_WAIT_S
+        while True:
+            if getattr(event, "_gateway_active_turn_token", None):
+                return "accepted"
+            outcome = getattr(event, "_securecoms_outcome", None)
+            if outcome == "CANCELLED":
+                return "cancelled"
+            if outcome is not None:
+                return "accepted"  # finished (success or failure): never redeliver a poison turn
+            remaining = deadline - loop.time()
+            if remaining <= 0:
+                return "timeout"
+            await asyncio.sleep(min(_ACCEPT_POLL_S, remaining))
+
+    async def _ack_on_acceptance(self, mid: Any, key: Optional[str], event: Any) -> None:
+        try:
+            result = await self._await_acceptance(event)
+        except BaseException:
+            # Cancelled (disconnect) or broken: unacked, and forgotten so a
+            # redelivery to this same adapter runs the turn.
+            if key is not None:
+                self._deliveries.forget(key)
+            raise
+        if result == "cancelled":
+            # Hermes dropped it before persisting a marker: no Hermes resume
+            # will cover it. Fail it back to the daemon, which requeues it
+            # behind its backoff (ws-server.ts nack) instead of holding the
+            # channel until this socket closes.
+            if key is not None:
+                self._deliveries.forget(key)
+            await self._send_nack(mid)
+            return
+        if result == "timeout":
+            logger.info("SecureComs: turn not yet accepted by Hermes at the ack bound; acking it")
+        # Done BEFORE the send: a redelivery racing in is acked, never re-run.
+        if key is not None:
+            self._deliveries.finish(key)
+        await self._send_ack(mid)
+
+    async def _send_ack(self, mid: Any) -> None:
+        """Ack on the CURRENT socket. The daemon's ack handler retires the id
+        durably for the agent (ackRuntimeMessages), not per socket, and also
+        clears it from that socket's in-flight map, which after a reconnect
+        holds the redelivered copy. With no socket the ack is dropped: the
+        ledger already says done, so the redelivery is acked on arrival."""
+        key = mid if isinstance(mid, str) and mid else None
+        ws = self._ws
+        if ws is None:
+            logger.debug("SecureComs: no daemon link for an ack; it is sent on reconnect")
+            self._hold_unsent_ack(key)
+            return
+        try:
+            await ws.send_json({"type": "ack", "message_id": mid})
+        except Exception as e:
+            logger.warning(
+                "SecureComs: ack failed (error_class=%s)",
+                _error_class(e),
+            )
+            self._hold_unsent_ack(key)
+            return
+        if key is not None:
+            self._unsent_acks.pop(key, None)
+            self._deliveries.unpin(key)
+
+    def _hold_unsent_ack(self, key: Optional[str]) -> None:
+        if key is None:
+            return
+        self._unsent_acks.pop(key, None)
+        self._unsent_acks[key] = None
+        self._deliveries.pin(key)
+
+    async def _flush_unsent_acks(self) -> None:
+        """Send acks dropped while the link was down, on the new socket."""
+        for key in list(self._unsent_acks):
+            if self._ws is None:
+                return
+            await self._send_ack(key)
+            if key in self._unsent_acks:
+                return  # the send failed again; keep the rest for next time
+
+    async def _send_nack(self, mid: Any) -> None:
+        ws = self._ws
+        if ws is None or not isinstance(mid, str) or not mid:
+            return  # the daemon re-buffers whatever is unacked when the socket closes
+        try:
+            await ws.send_json({"type": "nack", "message_id": mid})
+        except Exception as e:
+            logger.debug(
+                "SecureComs: nack failed (error_class=%s)",
+                _error_class(e),
+            )
+
+    async def _dispatch(self, frame: Dict[str, Any]) -> Optional[Any]:
+        """Hand one frame to Hermes. Returns the MessageEvent passed to
+        handle_message, or None when the frame was dropped before Hermes."""
+        if not self._message_handler:
+            return None
         if securecoms_transport.should_drop_inbound(frame, self._bound_identity):
-            return  # echo guard (contract §4.4): never re-feed our own sends
+            return None  # echo guard (contract §4.4): never re-feed our own sends
         channel_id = frame.get("channel_id", "")
         sender_id = frame.get("sender_id", "")
         text = frame.get("text", "")
+        if channel_id not in self._channels and self._session is not None and self._may_look_up(channel_id):
+            # A channel created after connect: look it up before guessing, at
+            # most once per _UNKNOWN_CHANNEL_RETRY_S per channel (review r2).
+            await self._refresh_channels()
         meta = self._channels.get(channel_id, {})
-        chat_type = "dm" if meta.get("is_dm", True) else "group"
+        # Review r1 M3: a channel whose metadata is not cached yet is a GROUP
+        # (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"
 
-        global _FRAMES_WITHOUT_AUTHORIZATION
+        global _FRAMES_WITHOUT_AUTHORIZATION, _ATTACHMENTS_DROPPED
         if not isinstance(frame.get("authorization"), dict):
             _FRAMES_WITHOUT_AUTHORIZATION += 1
             if _FRAMES_WITHOUT_AUTHORIZATION % 100 == 1:
@@ -492,10 +848,11 @@ class SecureComsAdapter(BasePlatformAdapter):
         _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.
+            # daemon did not grant tools never reaches it. Acked at once by
+            # _receive_message.
             logger.warning("SecureComs: refused a turn without a tool grant (tool veto unavailable)")
             await self._notify_refused(channel_id, frame)
-            return
+            return None
 
         source = self.build_source(
             chat_id=channel_id,
@@ -509,12 +866,32 @@ class SecureComsAdapter(BasePlatformAdapter):
             # 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
+        # Image/file attachments the daemon decrypted to disk ride as Hermes
+        # media, the same shape Hermes's own Signal adapter emits
+        # (gateway/platforms/signal.py): media_urls = local file paths,
+        # media_types = mimes, message_type from the first matching MIME
+        # prefix, else DOCUMENT. An image with no caption still runs a turn.
+        attachments, dropped = securecoms_transport.scan_inbound_attachments(frame)
+        if dropped:
+            # Content-free: a fixed line plus a process counter, never a path,
+            # name or mime (tests/test_logging_privacy.py bars dynamic args).
+            _ATTACHMENTS_DROPPED += dropped
+            logger.info("SecureComs: dropped inbound attachment(s) that failed validation")
+        media_kw: Dict[str, Any] = {}
+        message_type = MessageType.TEXT
+        if attachments:
+            media_kw = {
+                "media_urls": [p for p, _ in attachments],
+                "media_types": [m for _, m in attachments],
+            }
+            message_type = _message_type_for_mimes(media_kw["media_types"])
         event = MessageEvent(
-            text=text,
-            message_type=MessageType.TEXT,
+            text=text if isinstance(text, str) else "",
+            message_type=message_type,
             source=source,
             message_id=str(frame.get("message_id") or int(time.time() * 1000)),
             timestamp=datetime.now(),
+            **media_kw,
         )
         # Sender role rides as event metadata, never in the user text.
         metadata = getattr(event, "metadata", None)
@@ -532,7 +909,22 @@ 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)
+        return event
+
+    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)."""
+        now = time.monotonic()
+        last = self._unknown_channel_lookups.get(channel_id)
+        if last is not None and now - last < _UNKNOWN_CHANNEL_RETRY_S:
+            return False
+        self._unknown_channel_lookups.pop(channel_id, None)
+        self._unknown_channel_lookups[channel_id] = now
+        while len(self._unknown_channel_lookups) > _UNKNOWN_CHANNEL_LOOKUPS_MAX:
+            self._unknown_channel_lookups.pop(next(iter(self._unknown_channel_lookups)))
+        return True
 
     async def _notify_refused(self, channel_id: str, frame: Dict[str, Any]) -> None:
         """One short notice per channel that this agent cannot respond there.
@@ -639,7 +1031,7 @@ class SecureComsAdapter(BasePlatformAdapter):
             meta = self._channels.get(chat_id, {})
         return {
             "name": meta.get("name", chat_id),
-            "type": "dm" if meta.get("is_dm", True) else "group",
+            "type": "dm" if meta.get("is_dm") is True else "group",
             "chat_id": chat_id,
         }