agent-comms 1.4.0 → 1.4.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-comms",
   "description": "Cross-harness LLM agent communication bus — rooms, DMs, and presence",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "author": {
     "name": "ExaDev"
   },

package/README.md

@@ -1,6 +1,6 @@
 # Agent Comms
 
-Cross-harness communication bus for LLM agents: rooms, DMs, presence, and visibility over a TCP peer mesh with zero filesystem dependencies.
+Cross-harness communication mesh for LLM agents: rooms, DMs, presence, and visibility over TCP with zero filesystem dependencies.
 
 ## Why
 
@@ -14,24 +14,48 @@ The project began as a filesystem-based bus (`~/.agents/bus/`), where agents rea
 
 Each bridge instance is a peer in a TCP mesh on localhost. The first instance to start becomes the **coordinator** (port 19876). Subsequent instances connect to the coordinator, receive the peer list, and establish direct data connections with every other peer.
 
-```
-Agent A (pi)                          Agent B (Claude Code)
-   │                                       │
-   │  pi bridge  ◀──TCP localhost──▶  Claude bridge
-   │      │                                │
-   │  agent_comms(                    channel notification
-   │    "send",                             │
-   │    ...                           Claude surfaces it
-   │  )                                to the LLM
-   │      │
-   │  push to B's bridge ───────────▶ handled
+```mermaid
+graph LR
+    subgraph Agent A ["Agent A (pi)"]
+        A_LLM["LLM"]
+        A_Bridge["pi bridge"]
+    end
+    subgraph Agent B ["Agent B (Claude Code)"]
+        B_Bridge["Claude bridge"]
+        B_LLM["LLM"]
+    end
+    A_LLM -- "agent_comms(send, ...)" --> A_Bridge
+    A_Bridge -- "TCP localhost" --> B_Bridge
+    B_Bridge -- "channel notification" --> B_LLM
 ```
 
 All state is held in memory and synchronised between peers. Delivery events are pushed directly over TCP: no polling, no filesystem, no daemon process.
 
 ### Coordinator pattern
 
-- **Well-known port** 19876 on localhost, the only agreed-upon constant
+```mermaid
+sequenceDiagram
+    participant P1 as Peer 1 (first to start)
+    participant P2 as Peer 2
+    participant P3 as Peer 3
+    P1->>P1: binds port 19876 → becomes coordinator
+    P2->>P1: connect to 19876
+    P1-->>P2: peer list [P1]
+    P2->>P1: establish data connection
+    P3->>P1: connect to 19876
+    P1-->>P3: peer list [P1, P2]
+    P3->>P1: establish data connection
+    P3->>P2: establish data connection
+    Note over P1,P3: All peers now connected directly
+    rect rgb(255, 230, 230)
+        Note over P1: Coordinator crashes
+        P2->>P2: race to bind 19876
+        P3->>P3: race to bind 19876
+        Note over P2,P3: ~100ms recovery, longest-running wins
+    end
+```
+
+- **Well-known port** 19876 on localhost — the only agreed-upon constant
 - The first instance to bind it becomes coordinator
 - Coordinator handles introductions only; it is not a router
 - On graceful shutdown, coordinator hands over to the longest-running peer
@@ -183,3 +207,65 @@ agent_comms({ action: "update", visibility: "hidden" })
 | `visible` | ✓ | ✓ | ✓ |
 | `hidden` | ✗ | ✓ (if ID known) | Members only |
 | `ghost` | ✗ | ✗ | ✗ |
+
+## Room member awareness
+
+When an agent joins a room, it receives a `room_members` delivery event listing all current members with their status. Existing members receive `member_joined` / `member_left` notifications (excluding the joining/leaving agent).
+
+```mermaid
+sequenceDiagram
+    participant A as Agent A (in room)
+    participant Mesh
+    participant B as Agent B (joining)
+    B->>Mesh: joinRoom("code-review")
+    Mesh-->>B: room_members { [{ id: A, status: active }] }
+    Mesh-->>A: member_joined { agent: B }
+    Note over A: A knows B arrived, B knows who is already there
+    rect rgb(255, 245, 230)
+        Note over B: B goes idle
+        B->>Mesh: update(status: idle)
+        Mesh-->>A: member_status { agent: B, status: idle }
+    end
+```
+
+When an agent's status changes (active / idle / busy / offline), all rooms it belongs to receive a `member_status` notification. This covers:
+
+- Explicit `update` action
+- Re-registration (offline → active)
+- Graceful shutdown
+- Stale agent cleanup (coordinator PID probe)
+
+## Delivery status and read receipts
+
+Messages carry a `readBy` field tracking which agents have consumed them. Status events are emitted to the sender automatically — no explicit action needed.
+
+```mermaid
+sequenceDiagram
+    participant A as Agent A (sender)
+    participant Mesh
+    participant B as Agent B (recipient)
+    A->>Mesh: send("Hello")
+    Mesh->>B: queue room_message
+    Mesh-->>A: delivery_status { delivered }
+    alt Push bridge (pi, Claude Code)
+        Mesh->>B: onDelivery fires
+    else Drain bridge (MCP, Codex, OpenCode)
+        B->>Mesh: drainDelivery()
+    end
+    Mesh->>Mesh: markRead(msgId, B)
+    Mesh-->>A: delivery_status { read }
+    Mesh->>Mesh: broadcast message_read patch
+```
+
+| Moment | Sender receives |
+|--------|-----------------|
+| Message queued for recipient | `delivery_status { status: "delivered" }` |
+| Recipient's bridge consumes it | `delivery_status { status: "read" }` |
+
+Read receipts fire when `onDelivery` is called (push bridges: pi, Claude Code) or when `drainDelivery` is called (drain bridges: MCP, Codex, OpenCode). Cross-peer read receipts propagate via a `message_read` mesh patch.
+
+This works for both room messages and DMs.
+
+## Stale agent cleanup
+
+The coordinator probes registered agent PIDs every 5 seconds using signal 0 (existence check). Dead agents are marked offline and the status is broadcast to all peers. Prevents zombie agents accumulating in the mesh when bridges crash without calling `shutdown()`. The probe interval only runs on the coordinator — other peers are passive.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-comms",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Cross-harness communication bus for LLM agents — TCP peer mesh with rooms, DMs, presence, and real-time push delivery",
   "type": "module",
   "packageManager": "pnpm@10.33.0",