@securecoms/agent-bridge 0.23.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,7 +274,7 @@ 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
 ```
@@ -279,6 +288,78 @@ 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.
 
 **Keepalive.** The daemon pings every 30 seconds and reaps a socket that misses a pong. Clients using the standard WebSocket API answer pings automatically.

package/connectors/hermes/adapter.py

@@ -123,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
@@ -419,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,
@@ -428,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",
@@ -436,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/openclaw/openclaw-entry.inbound.test.ts

@@ -273,7 +273,8 @@ describe("openclaw-entry — inbound sender, session, authority, dedup (P0 Task
     const { instances } = await start(rt.runtime);
     deliver(instances[0], { channel_id: "chan-R", message_id: "m-R", sender_id: MEMBER_ID, text: "ping", authorization: auth("team_room") });
     await waitFor(() => acksOf(instances[0]).includes("m-R"));
-    expect(sends).toEqual([{ channel_id: "chan-R", text: "pong", in_reply_to: "m-R" }]);
+    // SEC-06 #18 (PR #716 review MEDIUM-2): each block carries a stable key.
+    expect(sends).toEqual([{ channel_id: "chan-R", text: "pong", in_reply_to: "m-R", idempotency_key: "m-R:0" }]);
   });
 
   // ---------------------------------------------------------------- 2 ----

package/connectors/openclaw/openclaw-entry.js

@@ -260,6 +260,7 @@ export class LoopbackChannel {
     this._seen = new Set();
     this._inFlight = new Set();
     this._failures = new Map();
+    this._blockSeq = new Map(); // SEC-06 #18: inReplyTo -> { seq, pending } (see _blockKey)
     // Consecutive failed turns. While > 0, a WS open does NOT reset the
     // reconnect backoff, so a failing turn is retried with growing delay
     // instead of a ~250 ms redelivery loop.
@@ -515,8 +516,32 @@ export class LoopbackChannel {
     }
   }
 
+  /**
+   * 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 `<inReplyTo>:<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.
+   */
+  _blockKey(inReplyTo, text) {
+    let st = this._blockSeq.get(inReplyTo);
+    if (!st) {
+      st = { seq: 0, pending: undefined };
+      if (this._blockSeq.size >= SEEN_MAX) {
+        const oldest = this._blockSeq.keys().next();
+        if (!oldest.done) this._blockSeq.delete(oldest.value);
+      }
+      this._blockSeq.set(inReplyTo, st);
+    }
+    if (st.pending !== undefined && st.pending !== text) st.seq++;
+    st.pending = text;
+    return { key: `${inReplyTo}:${st.seq}`, st };
+  }
+
   /** Send a reply into a specific SecureComs channel via the daemon. */
   async send(channelId, text, inReplyTo) {
+    const block = inReplyTo ? this._blockKey(inReplyTo, text) : null;
     const r = await fetch(`${this.bridgeUrl}/v1/send`, {
       method: "POST",
       headers: { "content-type": "application/json", authorization: `Bearer ${this.token}` },
@@ -524,9 +549,14 @@ export class LoopbackChannel {
         channel_id: channelId,
         text,
         ...(inReplyTo ? { in_reply_to: inReplyTo } : {}),
+        ...(block ? { idempotency_key: block.key } : {}),
       }),
     });
     if (!r.ok) throw new Error(`send failed: ${r.status} ${(await r.text()).slice(0, 200)}`);
+    if (block) {
+      block.st.seq++;
+      block.st.pending = undefined;
+    }
     return r.json();
   }
 

package/connectors/openclaw/openclaw-entry.smoke.test.ts

@@ -47,6 +47,32 @@ describe("openclaw-entry", () => {
       channel_id: "channel-1",
       text: "reply text",
       in_reply_to: "inbound-1",
+      idempotency_key: "inbound-1:0",
     }]);
   });
+
+  it("SEC-06 #18: every reply block gets a stable idempotency_key (identical blocks stay two messages; a retry reuses its key)", async () => {
+    const keys: unknown[] = [];
+    let ok = true;
+    vi.stubGlobal("fetch", async (_url: string, init: RequestInit) => {
+      keys.push((JSON.parse(String(init.body)) as Record<string, unknown>).idempotency_key);
+      return ok
+        ? { ok: true, json: async () => ({ message_id: "m" }) }
+        : { ok: false, status: 500, text: async () => "boom" };
+    });
+    const { LoopbackChannel } = await import("./openclaw-entry.js");
+    const channel = new LoopbackChannel({ boundIdentity: "agent-1" });
+    channel.bridgeUrl = "http://127.0.0.1:7090";
+    channel.token = "token";
+    await channel.send("c", "ok", "in-1");
+    await channel.send("c", "ok", "in-1"); // a second, identical block
+    ok = false;
+    await expect(channel.send("c", "third", "in-1")).rejects.toThrow();
+    await expect(channel.send("c", "third", "in-1")).rejects.toThrow(); // retry of the same block
+    ok = true;
+    await channel.send("c", "fourth", "in-1"); // the unconfirmed block is abandoned
+    await channel.send("c", "other", "in-2");
+    await channel.send("c", "no correlation");
+    expect(keys).toEqual(["in-1:0", "in-1:1", "in-1:2", "in-1:2", "in-1:3", "in-2:0", undefined]);
+  });
 });