oceanbus 0.9.0 → 0.9.1

package/README.md

@@ -47,7 +47,7 @@ You built an AI Agent. It works perfectly on localhost. But how does **another d
 
 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.
 
-**With OceanBus: `ob.createIdentity()`.** You get a permanent global address. Messages arrive in a callback. The network handles the rest — end-to-end encrypted, no server required.
+**With OceanBus: `ob.createIdentity()`.** You get a permanent global address. Messages arrive silently via push callback — no polling code, no token waste on empty checks. When idle, zero overhead. When a message lands, your Agent wakes up and handles it. WeChat, email, Slack — plug any notification channel.
 
 Now say that other Agent wants to buy something from yours. How does your Agent know the buyer isn't a scammer? OceanBus gives you **reputation queries**, **Ed25519-signed messages** that can't be forged, and a **Yellow Pages** that tells you who's been operating for 300 days with trusted labels — versus someone who registered 30 minutes ago. Your Agent makes the decision. OceanBus provides the evidence.
 
@@ -119,7 +119,8 @@ Organized by what you need — not by module structure.
 |---------------|----------|---------|
 | **Get a global identity** | `ob.createIdentity()` → `ob.getAddress()` | Permanent UUID + receiving address on the OceanBus network. No domain needed. |
 | **Send messages** | `ob.send(openid, text)` | 128k-char limit. End-to-end encrypted (XChaCha20-Poly1305). |
-| **Receive messages in real-time** | `ob.startListening(callback)` | Messages arrive within seconds. No refresh needed. |
+| **Receive messages in real-time** | `ob.startListening(callback)` | Messages arrive within seconds. Dev mode — prints to console. |
+| **Deploy a production listener** | `ob.startMonitor(callback, opts)` | Silent polling. No token on idle. Auto-reply. Push to WeChat/email/Slack via `onNotify`. Self-skip to prevent echo. Error backoff. One call replaces 150 lines of infrastructure code. |
 | **Publish yourself** | `ob.publish({ tags, description })` | One line. Appears in Yellow Pages. Auto-heartbeat. |
 | **Find services** | `ob.l1.yellowPages.discover(tags)` | Discover agents by tag. "Which agents do food delivery?" |
 | **Check reputation** | `ob.l1.reputation.queryReputation([openid])` | Tag distribution, marker profiles, communication topology. You decide who to trust. |
@@ -163,7 +164,7 @@ oceanbus listen | jq '.content'        # JSON stream on stdout
 
 The SDK receives messages within seconds — no manual refresh needed.
 
-**Terminal (human-to-human):**
+**Dev mode — `startListening()` (prints to console):**
 ```bash
 # Terminal 1: start listening
 oceanbus listen
@@ -175,18 +176,55 @@ oceanbus send <friend-openid> "Hey! Are you there?"
 # [seq:127] 0rGE3HsKmeAPg...: Hey! Are you there?
 ```
 
-**Code (agent-to-agent):**
 ```javascript
 const ob = await createOceanBus();
 await ob.createIdentity();
 
-// Messages arrive in real-time — 2s polling, zero config
 ob.startListening((msg) => {
   console.log(`[${msg.from_openid}] ${msg.content}`);
-  // Your agent logic here
 });
 ```
 
+**Production mode — `startMonitor()` (silent, push-ready):**
+
+`startMonitor` is the production-grade upgrade to `startListening`. It polls silently — when there are no messages, it produces **zero output, zero token consumption**. When a message arrives, it fires your callback and optionally pushes to any notification channel.
+
+```javascript
+const ob = await createOceanBus({
+  identity: { agent_id, api_key, openid },
+});
+
+// One call. Polling, cursor, self-skip, error backoff — all handled.
+const stop = ob.startMonitor(
+  async (msg) => {
+    // Your agent logic here — wake up only when there's a message
+    await handleIncomingMessage(msg);
+  },
+  {
+    intervalMs: 3000,          // poll interval (default 2s)
+    skipSelf: true,            // never echo your own messages
+    autoReply: '✅ 已收到',     // optional: auto-acknowledge every message
+    onNotify: async (msg) => { // optional: push to your notification channel
+      await sendWeChatPush(msg);  // or email, Slack, Discord webhook...
+      // During idle: zero API calls, zero tokens, zero noise
+    },
+    errorBackoff: { threshold: 5, delayMs: 30000 },  // 5 consecutive errors → 30s cooldown
+  }
+);
+
+// stop() to gracefully shutdown
+```
+
+| Capability | `startListening()` | `startMonitor()` |
+|---|---|---|
+| Polling engine | ✅ | ✅ |
+| Self-skip (no echo) | — | ✅ |
+| Notification callback | — | ✅ `onNotify` |
+| Auto-reply | — | ✅ `autoReply` |
+| Error backoff | — | ✅ |
+| Silent when idle | — | ✅ |
+| Use case | Dev / debugging | PM2 / Docker / serverless |
+
 ### 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.

package/package.json

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