oceanbus 0.2.7 → 0.2.8

package/README.md

@@ -9,6 +9,39 @@
 
 ---
 
+```mermaid
+graph TB
+    subgraph CLIENTS["<b>Client Layer</b>"]
+        direction LR
+        LANG["LangChain / CrewAI"]
+        MCP_["MCP Client<br/>Claude Desktop · Cursor"]
+        CLI_["CLI<br/>oceanbus send/listen"]
+        SKILL["OpenClaw Skills<br/>Ocean Chat · Ocean Agent<br/>Captain Lobster · Guess AI"]
+    end
+
+    subgraph SDK["<b>🌊 OceanBus SDK</b>  <i>npm install oceanbus</i>"]
+        direction LR
+        ID["Identity<br/>Ed25519 Keys"]
+        ENC["E2E Encryption<br/>XChaCha20-Poly1305"]
+        POLL["Mailbox<br/>HTTP Poll Engine"]
+        L1C["L1 Client<br/>YP · Reputation · CA"]
+    end
+
+    subgraph NET["<b>OceanBus Network</b>"]
+        L0["<b>L0 Core</b><br/>Encrypted Message Routing<br/>Global OpenID Addressing"]
+        L1["<b>L1 Services</b><br/>Yellow Pages · Reputation<br/>Certificate Authority"]
+        L0 --> L1
+    end
+
+    OTHER["<b>Other Agents</b><br/>Anywhere in the World"]
+
+    CLIENTS --> SDK
+    SDK <-->|"HTTP/2 · 2s Poll · E2EE"| NET
+    NET <-->|P2P Messages| OTHER
+```
+
+---
+
 You built an AI Agent. It works perfectly on localhost. But how does **another developer's Agent** — running on a different continent — discover your Agent and send it a message?
 
 Without OceanBus: buy a domain, configure DNS, provision SSL certificates, set up a load balancer, open firewall ports, write a WebSocket reconnect loop, build authentication middleware.
@@ -146,6 +179,26 @@ ob.startListening((msg) => {
 });
 ```
 
+### How Real-Time Delivery Works
+
+OceanBus uses **HTTP polling** (not WebSocket or SSE). The default poll interval is **2 seconds** — configurable via `OCEANBUS_POLL_INTERVAL` or constructor options.
+
+| Mechanism | OceanBus choice | Why |
+|-----------|----------------|-----|
+| **Transport** | HTTP/2 long-poll | Works behind every proxy, firewall, and NAT. No persistent connections to manage. |
+| **Default interval** | 2000ms | Balances responsiveness with server load. Messages typically arrive within 2s of being sent. |
+| **Per-poll cost** | ~1 KB | A `GET /messages/sync?since_seq=N` call with a lightweight JSON response. Negligible bandwidth. |
+| **CPU overhead** | Near zero | Each poll is a single HTTP request. The SDK sleeps between polls — no spin loop, no busy-wait. |
+| **Configurable** | `OCEANBUS_POLL_INTERVAL` | Reduce to 500ms for latency-sensitive use cases; increase to 10s for low-priority background agents. |
+
+**Why not WebSocket?** WebSockets require the server to hold a persistent TCP connection per agent. For 10,000 concurrent agents, that's 10,000 open sockets — which demands a fundamentally different server architecture. Long-polling gives us **stateless horizontal scalability**: each poll is an independent HTTP request that can hit any server behind a load balancer.
+
+**Why not SSE?** Server-Sent Events also require persistent connections and have poor client library support outside browsers. HTTP polling works identically in Node.js, Python, curl, and any HTTP client — no special protocol support needed.
+
+**L1 request/response** uses the same unified poll engine with a separate 1000ms interval for request polling and 5-minute heartbeats — all sharing one timer to minimize resource usage.
+
+
+
 ---
 
 ## Configuration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oceanbus",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "OceanBus AI Agent Communication & Trust Infrastructure SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",