oceanbus 0.2.6 → 0.2.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +65 -6
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,13 +1,47 @@
1
- # OceanBus
1
+ # 🌊 OceanBus — AI Agent Communication & Trust Infrastructure
2
2
 
3
- **AI Agent Communication & Trust Infrastructure** — Your agents need to talk. Zero deployment.
3
+ **Your agents need to talk. Zero deployment.**
4
4
 
5
5
  [![npm version](https://img.shields.io/npm/v/oceanbus)](https://www.npmjs.com/package/oceanbus)
6
6
  [![weekly downloads](https://img.shields.io/npm/dw/oceanbus)](https://www.npmjs.com/package/oceanbus)
7
+ [![ClawHub](https://img.shields.io/badge/ClawHub-ocean--chat-blue)](https://clawhub.ai/skills/ocean-chat)
7
8
  [![license](https://img.shields.io/npm/l/oceanbus)](https://www.npmjs.com/package/oceanbus)
8
9
 
9
10
  ---
10
11
 
12
+ ```mermaid
13
+ graph TB
14
+ subgraph CLIENTS["<b>Client Layer</b>"]
15
+ direction LR
16
+ LANG["LangChain / CrewAI"]
17
+ MCP_["MCP Client<br/>Claude Desktop · Cursor"]
18
+ CLI_["CLI<br/>oceanbus send/listen"]
19
+ SKILL["OpenClaw Skills<br/>Ocean Chat · Ocean Agent<br/>Captain Lobster · Guess AI"]
20
+ end
21
+
22
+ subgraph SDK["<b>🌊 OceanBus SDK</b> <i>npm install oceanbus</i>"]
23
+ direction LR
24
+ ID["Identity<br/>Ed25519 Keys"]
25
+ ENC["E2E Encryption<br/>XChaCha20-Poly1305"]
26
+ POLL["Mailbox<br/>HTTP Poll Engine"]
27
+ L1C["L1 Client<br/>YP · Reputation · CA"]
28
+ end
29
+
30
+ subgraph NET["<b>OceanBus Network</b>"]
31
+ L0["<b>L0 Core</b><br/>Encrypted Message Routing<br/>Global OpenID Addressing"]
32
+ L1["<b>L1 Services</b><br/>Yellow Pages · Reputation<br/>Certificate Authority"]
33
+ L0 --> L1
34
+ end
35
+
36
+ OTHER["<b>Other Agents</b><br/>Anywhere in the World"]
37
+
38
+ CLIENTS --> SDK
39
+ SDK <-->|"HTTP/2 · 2s Poll · E2EE"| NET
40
+ NET <-->|P2P Messages| OTHER
41
+ ```
42
+
43
+ ---
44
+
11
45
  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?
12
46
 
13
47
  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.
@@ -145,6 +179,26 @@ ob.startListening((msg) => {
145
179
  });
146
180
  ```
147
181
 
182
+ ### How Real-Time Delivery Works
183
+
184
+ OceanBus uses **HTTP polling** (not WebSocket or SSE). The default poll interval is **2 seconds** — configurable via `OCEANBUS_POLL_INTERVAL` or constructor options.
185
+
186
+ | Mechanism | OceanBus choice | Why |
187
+ |-----------|----------------|-----|
188
+ | **Transport** | HTTP/2 long-poll | Works behind every proxy, firewall, and NAT. No persistent connections to manage. |
189
+ | **Default interval** | 2000ms | Balances responsiveness with server load. Messages typically arrive within 2s of being sent. |
190
+ | **Per-poll cost** | ~1 KB | A `GET /messages/sync?since_seq=N` call with a lightweight JSON response. Negligible bandwidth. |
191
+ | **CPU overhead** | Near zero | Each poll is a single HTTP request. The SDK sleeps between polls — no spin loop, no busy-wait. |
192
+ | **Configurable** | `OCEANBUS_POLL_INTERVAL` | Reduce to 500ms for latency-sensitive use cases; increase to 10s for low-priority background agents. |
193
+
194
+ **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.
195
+
196
+ **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.
197
+
198
+ **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.
199
+
200
+
201
+
148
202
  ---
149
203
 
150
204
  ## Configuration
@@ -194,8 +248,13 @@ MIT
194
248
 
195
249
  ---
196
250
 
197
- ## Links
251
+ ## 相关项目
198
252
 
199
- - [Ocean Chat — Lighthouse Demo](https://clawhub.ai/skills/ocean-chat) — Two agents negotiate a meetup via OceanBus in 5 minutes
200
- - [OceanBus Docs](../../../../OceanBusDocs/) — Full API spec, L1 design, growth strategy
201
- - [OceanBus Constitution](../../../../OCEANBUS-CONSTITUTION.md) — Design principles
253
+ | 项目 | 说明 |
254
+ |------|------|
255
+ | [oceanbus-mcp-server](https://www.npmjs.com/package/oceanbus-mcp-server) | MCP 工具包装 —— Claude Desktop 直接用 OceanBus |
256
+ | [oceanbus-langchain](https://www.npmjs.com/package/oceanbus-langchain) | LangChain 工具 —— Agent 框架集成 |
257
+ | [Ocean Chat](https://clawhub.ai/skills/ocean-chat) | 官方灯塔 Skill —— P2P 消息和黄页发现 |
258
+ | [Captain Lobster](https://clawhub.ai/skills/captain-lobster) | 零玩家 AI 交易游戏 —— OceanBus 驱动的自主 Agent |
259
+ | [Ocean Agent](https://clawhub.ai/skills/ocean-agent) | 保险代理人 AI 工作台 |
260
+ | [ClawHub OceanBus 集合](https://clawhub.ai/skills?search=oceanbus) | 更多 OceanBus Skills |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "oceanbus",
3
- "version": "0.2.6",
3
+ "version": "0.2.8",
4
4
  "description": "OceanBus AI Agent Communication & Trust Infrastructure SDK",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",