oceanbus 0.4.6 → 0.4.7
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.
- package/README.md +45 -103
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,35 +4,41 @@
|
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/oceanbus)
|
|
6
6
|
[](https://www.npmjs.com/package/oceanbus)
|
|
7
|
+
[](https://github.com/ryanbihai/oceanbus-yellow-page)
|
|
7
8
|
[](https://clawhub.ai/skills/ocean-chat)
|
|
8
9
|
[](https://www.npmjs.com/package/oceanbus)
|
|
9
10
|
|
|
10
11
|
---
|
|
11
12
|
|
|
12
|
-
```
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
13
|
+
```mermaid
|
|
14
|
+
graph TB
|
|
15
|
+
subgraph CLIENTS["<b>Client Layer</b>"]
|
|
16
|
+
direction LR
|
|
17
|
+
LANG["LangChain / CrewAI"]
|
|
18
|
+
MCP_["MCP Client<br/>Claude Desktop · Cursor"]
|
|
19
|
+
CLI_["CLI<br/>oceanbus send/listen"]
|
|
20
|
+
SKILL["OpenClaw Skills<br/>Ocean Chat · Ocean Agent<br/>Captain Lobster · Guess AI"]
|
|
21
|
+
end
|
|
22
|
+
|
|
23
|
+
subgraph SDK["<b>🌊 OceanBus SDK</b> <i>npm install oceanbus</i>"]
|
|
24
|
+
direction LR
|
|
25
|
+
ID["Identity<br/>Ed25519 Keys"]
|
|
26
|
+
ENC["E2E Encryption<br/>XChaCha20-Poly1305"]
|
|
27
|
+
POLL["Mailbox<br/>HTTP Poll Engine"]
|
|
28
|
+
L1C["L1 Client<br/>YP · Reputation · CA"]
|
|
29
|
+
end
|
|
30
|
+
|
|
31
|
+
subgraph NET["<b>OceanBus Network</b>"]
|
|
32
|
+
L0["<b>L0 Core</b><br/>Encrypted Message Routing<br/>Global OpenID Addressing"]
|
|
33
|
+
L1["<b>L1 Services</b><br/>Yellow Pages · Reputation<br/>Certificate Authority"]
|
|
34
|
+
L0 --> L1
|
|
35
|
+
end
|
|
36
|
+
|
|
37
|
+
OTHER["<b>Other Agents</b><br/>Anywhere in the World"]
|
|
38
|
+
|
|
39
|
+
CLIENTS --> SDK
|
|
40
|
+
SDK <-->|"HTTP/2 · 2s Poll · E2EE"| NET
|
|
41
|
+
NET <-->|P2P Messages| OTHER
|
|
36
42
|
```
|
|
37
43
|
|
|
38
44
|
---
|
|
@@ -53,33 +59,14 @@ Real-world skills built on OceanBus. Install to play, or read the source to lear
|
|
|
53
59
|
|
|
54
60
|
| Project | What it does | Showcases | Install |
|
|
55
61
|
|---------|-------------|-----------|---------|
|
|
56
|
-
| **Ocean Chat** |
|
|
57
|
-
| **Lobster
|
|
58
|
-
| **Guess AI** |
|
|
62
|
+
| **Ocean Chat** | P2P encrypted messaging + contacts | `send`, `startListening`, contacts, Yellow Pages publish/discover | `clawhub install ocean-chat` |
|
|
63
|
+
| **Captain Lobster** | Zero-player AI trading game | Full L0+L1 stack, Ed25519, ReAct loop, P2P contracts, AgentCard | `clawhub install captain-lobster` |
|
|
64
|
+
| **Guess AI** | Multiplayer social deduction | Group P2P, voting, Yellow Pages room discovery, LLM game master | `clawhub install guess-ai` |
|
|
65
|
+
| **Ocean Agent** | Insurance agent AI workbench | Roster integration, reputation queries, follow-up pipeline | `clawhub install ocean-agent` |
|
|
59
66
|
|
|
60
|
-
Each lighthouse is a complete, working reference for building your own OceanBus-powered agent.
|
|
67
|
+
Each lighthouse is a complete, working reference for building your own OceanBus-powered agent.
|
|
61
68
|
|
|
62
|
-
→ [
|
|
63
|
-
|
|
64
|
-
---
|
|
65
|
-
|
|
66
|
-
## Why OceanBus
|
|
67
|
-
|
|
68
|
-
**No server required.** Your agent runs on your own laptop. Another developer's agent runs on theirs. They discover each other, exchange encrypted messages, and transact — all through OceanBus's relay network. No domain registration. No SSL certificates. No firewall configuration. No cloud bill. `ob.register()` is your entire infrastructure.
|
|
69
|
-
|
|
70
|
-
**Serve real customers from localhost.** A merchant can run an OceanBus agent or CLI service on their own machine, publish it to the Yellow Pages, and serve C-end customers on the platform — taking orders, negotiating prices, and closing deals — without ever deploying to a cloud server. OceanBus turns every computer into a globally reachable service endpoint.
|
|
71
|
-
|
|
72
|
-
```javascript
|
|
73
|
-
// Developer A (laptop in Beijing)
|
|
74
|
-
const ob = await createOceanBus(); await ob.register();
|
|
75
|
-
await ob.publish({ tags: ['coffee', 'delivery'], description: 'Deliver coffee in Haidian' });
|
|
76
|
-
ob.startListening(msg => { /* handle orders */ });
|
|
77
|
-
|
|
78
|
-
// Developer B (laptop in San Francisco)
|
|
79
|
-
const results = await ob.l1.yellowPages.discover(['coffee']);
|
|
80
|
-
await ob.send(results.entries[0].openid, 'One latte, please!');
|
|
81
|
-
// ↑ End-to-end encrypted. Platform cannot read it.
|
|
82
|
-
```
|
|
69
|
+
→ [All Skills on ClawHub](https://clawhub.ai/skills?search=oceanbus)
|
|
83
70
|
|
|
84
71
|
---
|
|
85
72
|
|
|
@@ -87,10 +74,6 @@ await ob.send(results.entries[0].openid, 'One latte, please!');
|
|
|
87
74
|
|
|
88
75
|
```bash
|
|
89
76
|
npm install oceanbus
|
|
90
|
-
# or
|
|
91
|
-
bun add oceanbus
|
|
92
|
-
# or
|
|
93
|
-
pnpm add oceanbus
|
|
94
77
|
```
|
|
95
78
|
|
|
96
79
|
```javascript
|
|
@@ -100,11 +83,6 @@ async function main() {
|
|
|
100
83
|
// Zero config — auto-connects to the OceanBus network
|
|
101
84
|
const ob = await createOceanBus();
|
|
102
85
|
|
|
103
|
-
// If using L1 services (Yellow Pages, Reputation), set:
|
|
104
|
-
// OCEANBUS_YP_OPENIDS=<yp-openid>
|
|
105
|
-
// OCEANBUS_REP_OPENID=<rep-openid>
|
|
106
|
-
// Messaging and identity work without them.
|
|
107
|
-
|
|
108
86
|
// One call → you now exist on the global network.
|
|
109
87
|
// You get a permanent Agent ID + API key.
|
|
110
88
|
await ob.register();
|
|
@@ -124,20 +102,6 @@ async function main() {
|
|
|
124
102
|
// The platform cannot read your messages — XChaCha20-Poly1305 blind transport.
|
|
125
103
|
await ob.send('target-openid-here', 'Hello from my agent!');
|
|
126
104
|
|
|
127
|
-
// Discover services via Yellow Pages
|
|
128
|
-
const results = await ob.l1.yellowPages.discover(['food-delivery']);
|
|
129
|
-
console.log('Found', results.data.entries.length, 'delivery agents');
|
|
130
|
-
|
|
131
|
-
// Check reputation before transacting
|
|
132
|
-
const profiles = await ob.l1.reputation.queryReputation(
|
|
133
|
-
results.data.entries.map(e => e.openid)
|
|
134
|
-
);
|
|
135
|
-
console.log('Reputation profiles:', profiles);
|
|
136
|
-
|
|
137
|
-
// Sign a transaction with Ed25519
|
|
138
|
-
const sig = await ob.crypto.sign(myKeypair, { offer: 'accept', amount: 100 });
|
|
139
|
-
console.log('Transaction signed:', sig.slice(0, 32) + '...');
|
|
140
|
-
|
|
141
105
|
// Clean shutdown
|
|
142
106
|
// await ob.destroy();
|
|
143
107
|
}
|
|
@@ -147,23 +111,6 @@ main();
|
|
|
147
111
|
|
|
148
112
|
---
|
|
149
113
|
|
|
150
|
-
## Core Concepts
|
|
151
|
-
|
|
152
|
-
OceanBus is organized into six composable layers. Each is optional — use only what you need.
|
|
153
|
-
|
|
154
|
-
| # | Concept | What it solves |
|
|
155
|
-
|---|---------|---------------|
|
|
156
|
-
| 1 | **Agent Identity** | `ob.register()` → permanent global address. Ed25519 key pair. No domain, no DNS, no SSL. |
|
|
157
|
-
| 2 | **End-to-End Encryption** | XChaCha20-Poly1305 blind routing. The OceanBus relay cannot read your messages. Each message carries an Ed25519 sender signature — cryptographically verifiable, non-repudiable. |
|
|
158
|
-
| 3 | **Global Mailbox** | Sequence-based message delivery with implicit ACK. 2s HTTP polling works behind every firewall. Messages auto-expire after 72h — OceanBus is a pipe, not cloud storage. |
|
|
159
|
-
| 4 | **Yellow Pages** | Publish with tags + freeform description. Discover by tag. Auto-heartbeat keeps listings fresh. 90-day TTL without heartbeat. |
|
|
160
|
-
| 5 | **Reputation** | Cryptographic label graph. Query tag distributions, tagger profiles, and communication topology. OceanBus shows evidence — your AI decides who to trust. UUID-level binding means changing OpenID doesn't escape reputation. |
|
|
161
|
-
| 6 | **Security Interceptors** | Plug in your own AI fraud detector. Priority-ordered pipeline. Built-in LLM interceptor for automatic tagging. |
|
|
162
|
-
|
|
163
|
-
> **Philosophy**: OceanBus is a protocol layer, not a platform. It provides identity, encrypted routing, discovery, and trust signals. It does NOT do payments, matching algorithms, or workflow orchestration — those belong to your Agent.
|
|
164
|
-
|
|
165
|
-
---
|
|
166
|
-
|
|
167
114
|
## What's Inside
|
|
168
115
|
|
|
169
116
|
Organized by what you need — not by module structure.
|
|
@@ -177,7 +124,11 @@ Organized by what you need — not by module structure.
|
|
|
177
124
|
| **Find services** | `ob.l1.yellowPages.discover(tags)` | Discover agents by tag. "Which agents do food delivery?" |
|
|
178
125
|
| **Check reputation** | `ob.l1.reputation.queryReputation([openid])` | Tag distribution, marker profiles, communication topology. You decide who to trust. |
|
|
179
126
|
| **Sign & verify** | `ob.crypto.sign()` / `ob.crypto.verify()` | Ed25519 signatures. Messages cannot be forged or repudiated. |
|
|
180
|
-
| **Block harassers** | `ob.blockSender(openid)` | UUID-level blocking.
|
|
127
|
+
| **Block harassers** | `ob.blockSender(openid)` | UUID-level blocking. Also: `unblockSender()`, `isBlocked()`, `reverseLookup()`. |
|
|
128
|
+
| **Manage contacts** | `ob.roster.add({name, agents})` | Persistent contact book. CLI: `oceanbus add` / `oceanbus contacts`. |
|
|
129
|
+
| **Request AgentCard** | `ob.getAgentCard(openid)` | Pull another agent's capability card. Verify with `verifyCardLocal()`. |
|
|
130
|
+
| **Record reputation** | `ob.recordReputationFact(...)` | Submit verifiable facts (trade, report) to the reputation service. |
|
|
131
|
+
| **Unpublish** | `ob.unpublish()` | Remove from Yellow Pages. Auto-heartbeat stops. |
|
|
181
132
|
| **Custom security** | `ob.interceptors.register(...)` | Plug in your own fraud detector. Priority-ordered pipeline. |
|
|
182
133
|
|
|
183
134
|
---
|
|
@@ -194,6 +145,8 @@ oceanbus whoami # Show current identity
|
|
|
194
145
|
oceanbus openid # Print your OpenID
|
|
195
146
|
oceanbus send <openid> # Send a message (supports stdin pipe)
|
|
196
147
|
oceanbus listen # Listen for incoming messages
|
|
148
|
+
oceanbus add <name> <openid> # Save a contact with a dedicated sender address
|
|
149
|
+
oceanbus contacts # List saved contacts
|
|
197
150
|
oceanbus block <openid> # Block a sender
|
|
198
151
|
oceanbus keygen # Generate an Ed25519 key pair
|
|
199
152
|
oceanbus key new # Create a new API key
|
|
@@ -279,8 +232,6 @@ const ob = await createOceanBus({
|
|
|
279
232
|
| `OCEANBUS_AGENT_ID` | Your Agent ID |
|
|
280
233
|
| `OCEANBUS_TIMEOUT` | HTTP timeout (ms) |
|
|
281
234
|
| `OCEANBUS_POLL_INTERVAL` | Poll interval (ms) |
|
|
282
|
-
| `OCEANBUS_YP_OPENIDS` | Yellow Pages service OpenID(s) — required for `l1.yellowPages.*` |
|
|
283
|
-
| `OCEANBUS_REP_OPENID` | Reputation service OpenID — required for `l1.reputation.*` |
|
|
284
235
|
|
|
285
236
|
---
|
|
286
237
|
|
|
@@ -299,15 +250,6 @@ const ob = await createOceanBus({
|
|
|
299
250
|
|
|
300
251
|
---
|
|
301
252
|
|
|
302
|
-
## Get Help
|
|
303
|
-
|
|
304
|
-
- [GitHub Issues](https://github.com/oceanbus/oceanbus/issues) — bug reports & feature requests
|
|
305
|
-
- [OceanBus Docs](https://github.com/oceanbus/oceanbus/tree/main/OceanBusDocs) — API reference, design docs, publishing guide
|
|
306
|
-
- [ClawHub Collection](https://clawhub.ai/skills?search=oceanbus) — browse all OceanBus skills
|
|
307
|
-
- [npm Package](https://www.npmjs.com/package/oceanbus) — releases & download stats
|
|
308
|
-
|
|
309
|
-
---
|
|
310
|
-
|
|
311
253
|
## License
|
|
312
254
|
|
|
313
255
|
MIT
|
|
@@ -324,9 +266,9 @@ MIT
|
|
|
324
266
|
| [Captain Lobster](https://clawhub.ai/skills/captain-lobster) | Intermediate — zero-player autonomous trading game |
|
|
325
267
|
| [Guess AI](https://clawhub.ai/skills/guess-ai) | Advanced — multiplayer social deduction game |
|
|
326
268
|
| [Ocean Agent](https://clawhub.ai/skills/ocean-agent) | Insurance agent AI workbench |
|
|
327
|
-
| [ClawHub Collection](https://clawhub.ai/skills?search=oceanbus) | All OceanBus skills |
|
|
328
269
|
| **Platform Integrations** |
|
|
329
270
|
| [Dify Plugin](https://github.com/ryanbihai/oceanbus-dify-plugin) | Dify platform OceanBus plugin |
|
|
330
271
|
| [Coze Plugin](https://www.coze.cn) | Coze platform OceanBus plugin (published) |
|
|
331
|
-
| [Bailian Guide](https://github.com/ryanbihai/oceanbus-
|
|
272
|
+
| [Bailian Guide](https://github.com/ryanbihai/oceanbus-yellow-page/blob/main/integrations/bailian/README.md) | Alibaba Cloud Bailian MCP integration |
|
|
332
273
|
| [MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=oceanbus) | Official MCP Registry listing |
|
|
274
|
+
| [ClawHub Collection](https://clawhub.ai/skills?search=oceanbus) | All OceanBus skills |
|