@securecoms/agent-bridge 0.21.0 → 0.24.0

package/README.md

@@ -213,6 +213,15 @@ HTTP 503
 
 Retry with exponential back-off. The channel becomes available once the owner's client adds the agent device to the MLS group.
 
+**`POST /v1/send` — 409 group_superseded**
+
+The channel's owner reset its secure session and this daemon still holds the previous MLS group. Nothing was sent or stored. The daemon asks the owner's client to re-admit it and never wipes its local state on this answer. Retry later with back-off; a reply sent with `in_reply_to` or `idempotency_key` is republished under the same message id once the daemon holds the new group. Until then the daemon holds that channel's inbound messages: they are not handed to the runtime and do not use up their delivery attempts, for at most 24 hours from the first refusal. Adoption and the re-admission request are skipped on FileSafe vault channels and on any channel the enclave channel listing does not show.
+
+```json
+HTTP 409
+{"error": "group_superseded", "message": "channel moved to a new secure group; not sent; retry after the agent rejoins"}
+```
+
 **`POST /v1/status` — state values**
 
 `state` must be one of `idle`, `working`, `stalled`, or `error`. `detail` is an optional free-form string.
@@ -241,7 +250,7 @@ All frames are JSON text.
     "sender_membership":"active"|"unknown", "tool_grants":[] } }
 { "type":"sent", "message_id":"..." }                       // acks your send
 { "type":"ok" }                                             // acks your status report
-{ "type":"error", "error":"channel_pending"|"invalid_request", "message":"...", "detail":"..." }
+{ "type":"error", "error":"channel_pending"|"invalid_request"|"group_superseded"|..., "message":"...", "detail":"..." }
 ```
 
 The daemon derives `authorization` only from the authenticated channel and
@@ -265,12 +274,91 @@ closed without exposing OpenClaw memory.
 **Agent → daemon**
 
 ```
-{ "type":"send", "channel_id":"...", "text":"...", "idempotency_key":"..." }   // idempotency_key optional
+{ "type":"send", "channel_id":"...", "text":"...", "in_reply_to":"...", "idempotency_key":"..." }   // both optional
 { "type":"status", "channel_id":"...", "state":"idle"|"working"|"stalled"|"error", "detail":"..." }
 { "type":"ack", "message_id":"..." }                        // confirms you consumed a delivered message
 ```
 
-**Acknowledge what you receive.** Inbound delivery is **at-least-once**. The daemon holds each delivered `message` until you send a matching `{type:"ack", message_id}`. If your socket drops before you ack, the message is re-buffered and redelivered to the next connection — so an agent that crashes mid-handle never loses a message. The cost is that you may occasionally see a message twice; dedup by `message_id`. (Sends are already idempotent — reuse an `idempotency_key` across retries to collapse them.) Ack as soon as you've durably handled a message, not before.
+**Acknowledge what you receive.** Inbound delivery is **at-least-once**. Before the remote server queue is acknowledged, the daemon seals each runtime-bound `message` into `bridge-state.db`. It remains durable until you send a matching `{type:"ack", message_id}`. If your socket, daemon, or host disappears first, the message is restored and redelivered to the next consumer in FIFO order. The cost is that you may occasionally see a message twice; dedup by `message_id`. Ack as soon as you've durably handled a message, not before.
+
+For the first-party runtime, a reply carries `in_reply_to`. The daemon persists a
+content-free reply receipt after publish, and a replacement runtime checks that
+receipt before running the turn again. This closes the publish-success/ACK-loss
+window where the result is known. It does not pretend an indeterminate external
+tool call is safe to repeat; those calls use the runtime's separate reconciliation
+ledger.
+
+**Replies are published at most once (SEC-06 #18).** A `send` that carries
+`in_reply_to` (or, on `/v1/ws`, an `idempotency_key`) is an idempotent reply:
+
+- Its `message_id` is a deterministic, keyed UUID of (agent identity, channel,
+  the inbound it answers, which part). The key is derived from the identity
+  seed, so other channel members cannot predict the id and publish under it
+  first. The voice fast path's reply id is keyed the same way. The
+  `idempotency_key` is never used as the `message_id` itself.
+- Before the publish, the daemon writes a durable reply intent to
+  `bridge-state.db`: the reply body and the signed envelope about to be sent,
+  both sealed like the rest of the store and dropped once the publish is
+  confirmed.
+- Every retry resends those exact envelope bytes, so a backend that already
+  accepted them answers with the original ack (even if the epoch has moved
+  since). A `message_in_flight` 409 (the original is still being processed)
+  is retried later with the same bytes, never re-encrypted: 3 in-process
+  retries with backoff, then the redelivery backoff and the delivery cap. The
+  reply is re-encrypted (same id, fresh nonce) only when the backend says the
+  earlier attempt was not accepted: a `replay_nonce` 409 on the exact bytes,
+  or `mls.stale_epoch`, which it answers only for an id it has not seen.
+- `message_id_conflict` means the id slot is held by OTHER bytes, never that
+  our reply was delivered: the cached envelope always holds the last bytes
+  posted under the id, and a resend of those bytes gets the original ack. So
+  the slot belongs to another message (for example an old reply whose intent
+  was pruned): an unkeyed part moves to the next part number, and a keyed one
+  fails with `invalid_request`.
+- If the inbound is redelivered while its reply has an intent (a 502 after the
+  backend committed, a crash before the receipt, a nack), the daemon
+  republishes that reply itself and acknowledges the inbound. The runtime is
+  not handed the message again, so the model does not run twice.
+- A `rate_limited` publish (the daemon's room floor or a backend 429) is
+  retried in-process with backoff, up to 3 times, before `rate_limited` is
+  returned. The intent stays pending, so the redelivery republishes it.
+- Parts are numbered from `bridge-state.db`, not from memory, so a restart
+  between two parts never reuses a published part's id. Intents are kept for
+  7 days (at most 5000).
+- **Send an `idempotency_key` per reply block.** Without one, a send whose text
+  equals the MOST RECENT part of the same `in_reply_to` is treated as a retry
+  of that part and returns its `message_id` without publishing. Two identical
+  consecutive blocks therefore become one message. With a key, each key is its
+  own part; resending the same key and text is a retry, and the same key with
+  different text is refused with `invalid_request`. The OpenClaw and Hermes
+  connectors send `<in_reply_to>:<n>` per block. `idempotency_key` is honoured
+  on both `/v1/ws` and `POST /v1/send`.
+- **Trade-off: a crash in the middle of a multi-part reply.** If the runtime
+  published part 1 of a reply and then the runtime, daemon or host died before
+  it produced part 2, the redelivered message is answered from the intents:
+  part 1 is republished (or confirmed) and the message is acknowledged. Part 2
+  is never produced, because producing it means running the model again, which
+  would write a new, different reply around a part 1 that was already sent.
+  The daemon chooses "no duplicate" over "complete".
+- An intent only answers a message the runtime was actually handed (one with a
+  delivery attempt). A reply that names a message still waiting in the buffer
+  does not stop that message reaching the runtime.
+- **Replies to a message more than 7 days old.** Intents are pruned after 7
+  days (or past 5000 rows), and a pruned intent's id is still held by the
+  reply the backend stored. Replying to that same inbound again then collides
+  with the old reply:
+  - a connector key reused after the prune (for example `X:0` again) is
+    refused with `400 invalid_request`, and that block is lost;
+  - an unkeyed reply moves past the old reply's parts one number at a time, at
+    most 8 per send. If the old reply had more than 8 parts, sends fail until
+    enough collided parts have been skipped (each failed send skips up to 8).
+- **Hermes: a block retried after a different block went out can be
+  published twice.** The Hermes connector reuses a block's key only while it
+  is the most recent unconfirmed block. If block A fails ambiguously (the
+  daemon may in fact have published it), then block B is sent, and then
+  Hermes retries A, the retry carries a new key and A appears twice. The
+  OpenClaw connector uses the same key rule; it does not retry a failed block
+  itself, so the same case arises there only if OpenClaw's own reply
+  dispatcher retries one.
 
 **One consumer at a time.** The daemon serves a single agent per process. Opening a second `/v1/ws` connection closes the first (newest wins, code `1000`); the replaced socket's un-acked messages are re-buffered for the new one. Don't run two consumers against one daemon expecting to share the stream.
 

package/connectors/hermes/adapter.py

@@ -81,6 +81,17 @@ _BINDING_PATH = os.path.join(_PLUGIN_DIR, "securecoms.binding.json")
 _CONNECTIONS_DIR = os.path.expanduser("~/.securecoms/connections")
 
 
+def _error_class(error: object) -> str:
+    """Return a bounded class name without reading exception prose."""
+    try:
+        name = type(error).__name__
+    except Exception:
+        return "Error"
+    if not name or len(name) > 64 or not name.replace("_", "a").isalnum():
+        return "Error"
+    return name
+
+
 def _read_file_text(path: str) -> str:
     with open(path, "r") as f:
         return f.read()
@@ -112,6 +123,8 @@ class SecureComsAdapter(BasePlatformAdapter):
         self.ws_url: Optional[str] = None
         self._token: Optional[str] = None
 
+        # 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
         self._ws = None
         self._recv_task: Optional[asyncio.Task] = None
@@ -184,7 +197,7 @@ class SecureComsAdapter(BasePlatformAdapter):
         self._recv_task = asyncio.create_task(self._supervise())
         self._tick_task = asyncio.create_task(self._tick_loop())
         self._mark_connected()
-        logger.info("SecureComs: connected to daemon at %s", self.bridge_url)
+        logger.info("SecureComs: connected to daemon")
         return True
 
     async def _open_ws(self) -> bool:
@@ -230,7 +243,7 @@ class SecureComsAdapter(BasePlatformAdapter):
         changed = self._hold_reason != reason
         self._hold_reason = reason
         if changed:
-            logger.warning("SecureComs: waiting for SecureComs daemon: %s", reason)
+            logger.warning("SecureComs: waiting for SecureComs daemon")
         self._set_fatal_error(
             "waiting_for_daemon",
             f"waiting for SecureComs daemon: {reason}",
@@ -253,7 +266,10 @@ class SecureComsAdapter(BasePlatformAdapter):
             except asyncio.CancelledError:
                 raise
             except Exception as e:
-                logger.warning("SecureComs: receive error: %s", e)
+                logger.warning(
+                    "SecureComs: receive failed (error_class=%s)",
+                    _error_class(e),
+                )
             if self._stopped:
                 break
             self._mark_disconnected()
@@ -311,7 +327,10 @@ class SecureComsAdapter(BasePlatformAdapter):
                             "is_dm": bool(c.get("is_dm")),
                         }
         except Exception as e:
-            logger.debug("SecureComs: channel refresh failed: %s", e)
+            logger.debug(
+                "SecureComs: channel refresh failed (error_class=%s)",
+                _error_class(e),
+            )
 
     # ── Status emit ───────────────────────────────────────────────────────
 
@@ -321,7 +340,10 @@ class SecureComsAdapter(BasePlatformAdapter):
         try:
             await self._ws.send_json(frame)
         except Exception as e:
-            logger.debug("SecureComs: status frame send failed: %s", e)
+            logger.debug(
+                "SecureComs: status frame send failed (error_class=%s)",
+                _error_class(e),
+            )
 
     async def _tick_loop(self) -> None:
         """Drives ChannelStatusManager.tick() so a channel goes idle after
@@ -334,7 +356,10 @@ class SecureComsAdapter(BasePlatformAdapter):
             except asyncio.CancelledError:
                 raise
             except Exception as e:
-                logger.debug("SecureComs: status tick error: %s", e)
+                logger.debug(
+                    "SecureComs: status tick failed (error_class=%s)",
+                    _error_class(e),
+                )
 
     # ── Inbound ───────────────────────────────────────────────────────────
 
@@ -360,7 +385,10 @@ class SecureComsAdapter(BasePlatformAdapter):
                             {"type": "ack", "message_id": frame.get("message_id")}
                         )
                     except Exception as e:
-                        logger.warning("SecureComs: ack failed: %s", e)
+                        logger.warning(
+                            "SecureComs: ack failed (error_class=%s)",
+                            _error_class(e),
+                        )
             elif msg.type in (aiohttp.WSMsgType.CLOSED, aiohttp.WSMsgType.ERROR):
                 return  # WS closed → supervisor reconnects
 
@@ -393,6 +421,29 @@ class SecureComsAdapter(BasePlatformAdapter):
 
     # ── Outbound ──────────────────────────────────────────────────────────
 
+    _BLOCK_SEQ_MAX = 1000
+
+    def _block_key(self, reply_to: str, content: str) -> Dict[str, Any]:
+        """SEC-06 #18: a stable idempotency_key per reply block.
+
+        The daemon matches a keyless retry only against the most recent part,
+        so two identical blocks would collapse into one message. The key is
+        ``<reply_to>:<n>``: n advances after a confirmed send, and also when a
+        new block arrives after an unconfirmed one (that block is abandoned). A
+        retry of the unconfirmed block (same text) reuses its key, so the daemon
+        never publishes it twice.
+        """
+        st = self._block_seq.get(reply_to)
+        if st is None:
+            if len(self._block_seq) >= self._BLOCK_SEQ_MAX:
+                self._block_seq.pop(next(iter(self._block_seq)))
+            st = {"seq": 0, "pending": None}
+            self._block_seq[reply_to] = st
+        if st["pending"] is not None and st["pending"] != content:
+            st["seq"] += 1
+        st["pending"] = content
+        return st
+
     async def send(
         self,
         chat_id: str,
@@ -402,6 +453,7 @@ class SecureComsAdapter(BasePlatformAdapter):
     ) -> SendResult:
         if not self._session or self._session.closed:
             return SendResult(success=False, error="not connected")
+        block = self._block_key(reply_to, content) if reply_to else None
         try:
             async with self._session.post(
                 f"{self.bridge_url}/v1/send",
@@ -410,9 +462,13 @@ class SecureComsAdapter(BasePlatformAdapter):
                     "channel_id": chat_id,
                     "text": content,
                     **({"in_reply_to": reply_to} if reply_to else {}),
+                    **({"idempotency_key": f"{reply_to}:{block['seq']}"} if block else {}),
                 },
             ) as r:
                 if r.status == 200:
+                    if block:
+                        block["seq"] += 1
+                        block["pending"] = None
                     j = await r.json()
                     await self._status.on_reply_posted(chat_id)
                     return SendResult(success=True, message_id=str(j.get("message_id")))

package/connectors/hermes/tests/test_adapter_wiring.py

@@ -352,8 +352,31 @@ class TestSendWiring:
             "channel_id": "chan-1",
             "text": "hello",
             "in_reply_to": "inbound-7",
+            "idempotency_key": "inbound-7:0",
         }
 
+    @pytest.mark.asyncio
+    async def test_send_gives_each_reply_block_a_stable_idempotency_key(self, monkeypatch):
+        # SEC-06 #18 (PR #716 review MEDIUM-2): the daemon matches a keyless
+        # retry only against the most recent part, so two identical blocks
+        # collapse into one message. A per-block key keeps them apart, and the
+        # SAME key on a retry of an unconfirmed block keeps it from publishing twice.
+        a, _ = make_adapter(monkeypatch)
+        a.bridge_url = "http://127.0.0.1:9001"
+        a._token = "tok"
+        a._session = FakeSession(post_response=(200, {"message_id": "m"}))
+        await a.send("chan-1", "ok", reply_to="in-1")
+        await a.send("chan-1", "ok", reply_to="in-1")  # a second, identical block
+        a._session._post_response = (500, "boom")
+        await a.send("chan-1", "third", reply_to="in-1")  # fails, unconfirmed
+        await a.send("chan-1", "third", reply_to="in-1")  # retry of the same block
+        a._session._post_response = (200, {"message_id": "m"})
+        await a.send("chan-1", "fourth", reply_to="in-1")  # the previous block is abandoned
+        await a.send("chan-1", "other", reply_to="in-2")
+        await a.send("chan-1", "no correlation")
+        keys = [c[2].get("idempotency_key") for c in a._session.post_calls]
+        assert keys == ["in-1:0", "in-1:1", "in-1:2", "in-1:2", "in-1:3", "in-2:0", None]
+
     @pytest.mark.asyncio
     async def test_send_failure_does_not_fire_on_reply_posted(self, monkeypatch):
         a, _ = make_adapter(monkeypatch)

package/connectors/hermes/tests/test_logging_privacy.py

@@ -0,0 +1,61 @@
+import ast
+from pathlib import Path
+
+from adapter import _error_class
+
+
+def _logging_violations(source: str) -> list[str]:
+    violations: list[str] = []
+    tree = ast.parse(source)
+    for node in ast.walk(tree):
+        if not (
+            isinstance(node, ast.Call)
+            and isinstance(node.func, ast.Attribute)
+            and isinstance(node.func.value, ast.Name)
+            and node.func.value.id == "logger"
+        ):
+            continue
+        if node.func.attr == "exception":
+            violations.append("logger.exception")
+        if not node.args or not (
+            isinstance(node.args[0], ast.Constant)
+            and isinstance(node.args[0].value, str)
+        ):
+            violations.append("dynamic format")
+            continue
+        rendered = node.args[0].value.lower()
+        if any(label in rendered for label in ("identity=", "channel=", "reason=", "url=")):
+            violations.append("sensitive field")
+        for arg in node.args[1:]:
+            if not (
+                isinstance(arg, ast.Call)
+                and isinstance(arg.func, ast.Name)
+                and arg.func.id == "_error_class"
+            ) and not (isinstance(arg, ast.Name) and arg.id == "backoff"):
+                violations.append("unbounded argument")
+    return violations
+
+
+def test_adapter_logging_source_is_content_free() -> None:
+    source = (Path(__file__).parents[1] / "adapter.py").read_text()
+    assert _logging_violations(source) == []
+
+
+def test_adapter_logging_guard_detects_dynamic_values() -> None:
+    hostile = '''
+logger.info(dynamic_format, identity)
+logger.warning("channel=%s", channel_id)
+logger.error("failed: %s", error)
+'''
+    violations = _logging_violations(hostile)
+    assert "dynamic format" in violations
+    assert "sensitive field" in violations
+    assert "unbounded argument" in violations
+
+
+def test_error_class_does_not_render_exception_prose() -> None:
+    class HostileError(RuntimeError):
+        def __str__(self) -> str:
+            raise AssertionError("exception prose was rendered")
+
+    assert _error_class(HostileError()) == "HostileError"