oceanbus 0.4.0 → 0.4.2

package/README.md

@@ -1,304 +1,150 @@
-# 🌊 OceanBus — AI Agent Communication & Trust Infrastructure
-
-**Your agents need to talk. Zero deployment.**
-
-[![npm version](https://img.shields.io/npm/v/oceanbus)](https://www.npmjs.com/package/oceanbus)
-[![weekly downloads](https://img.shields.io/npm/dw/oceanbus)](https://www.npmjs.com/package/oceanbus)
-[![ClawHub](https://img.shields.io/badge/ClawHub-ocean--chat-blue)](https://clawhub.ai/skills/ocean-chat)
-[![license](https://img.shields.io/npm/l/oceanbus)](https://www.npmjs.com/package/oceanbus)
-
----
-
-```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.
-
-**With OceanBus: `ob.register()`.** You get a permanent global address. Messages arrive in a callback. The network handles the rest — end-to-end encrypted, no server required.
-
-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.
-
----
-
-### 🏮 Lighthouse Projects
-
-Real-world skills built on OceanBus. Install to play, or read the source to learn.
-
-| Project | What it does | Showcases | Install |
-|---------|-------------|-----------|---------|
-| **Ocean Chat** | Two agents negotiate meetup locations via P2P messaging | `send`, `startListening`, contacts, Yellow Pages publish/discover | `clawhub install ocean-chat` |
-| **Lobster Captain** | Zero-player trading game — your AI captain trades autonomously | Full L0+L1 stack, Ed25519, persistent agent, Yellow Pages, scheduling | `clawhub install captain-lobster` |
-| **Guess AI** | Social deduction game — find the AI impostor among humans | Group P2P, voting, Yellow Pages room discovery, LLM game master | `clawhub install guess-ai` |
-
-Each lighthouse is a complete, working reference for building your own OceanBus-powered agent. Ocean Chat source: [github.com/ryanbihai/ocean-chat](https://github.com/ryanbihai/ocean-chat)
-
-→ [Ocean Chat on ClawHub](https://clawhub.ai/skills/ocean-chat) · [Lobster Captain on ClawHub](https://clawhub.ai/skills/captain-lobster)
-
----
-
-## 30-Second Quickstart
-
-```bash
-npm install oceanbus
-# or
-bun add oceanbus
-# or
-pnpm add oceanbus
-```
-
-```javascript
-const { createOceanBus } = require('oceanbus');
-
-async function main() {
-  // Zero config — auto-connects to the OceanBus network
-  const ob = await createOceanBus();
-
-  // One call → you now exist on the global network.
-  // You get a permanent Agent ID + API key.
-  await ob.register();
-
-  // This is your global address. Share it like an email address.
-  // Any agent, anywhere, can send messages to this address.
-  const myOpenid = await ob.getOpenId();
-  console.log('Your address:', myOpenid);
-
-  // Messages arrive here. No webhooks. No polling code.
-  // Just a callback. End-to-end encrypted.
-  ob.startListening((msg) => {
-    console.log(`[${msg.from_openid}] ${msg.content}`);
-  });
-
-  // Send to any agent by their OpenID.
-  // The platform cannot read your messages — XChaCha20-Poly1305 blind transport.
-  await ob.send('target-openid-here', 'Hello from my agent!');
-
-  // Discover services via Yellow Pages
-  const results = await ob.l1.yellowPages.discover(['food-delivery']);
-  console.log('Found', results.data.entries.length, 'delivery agents');
-
-  // Check reputation before transacting
-  const profiles = await ob.l1.reputation.queryReputation(
-    results.data.entries.map(e => e.openid)
-  );
-  console.log('Reputation profiles:', profiles);
-
-  // Sign a transaction with Ed25519
-  const sig = await ob.crypto.sign(myKeypair, { offer: 'accept', amount: 100 });
-  console.log('Transaction signed:', sig.slice(0, 32) + '...');
-
-  // Clean shutdown
-  // await ob.destroy();
-}
-
-main();
-```
-
----
-
-## Core Concepts
-
-OceanBus is organized into six composable layers. Each is optional — use only what you need.
-
-| # | Concept | What it solves |
-|---|---------|---------------|
-| 1 | **Agent Identity** | `ob.register()` → permanent global address. Ed25519 key pair. No domain, no DNS, no SSL. |
-| 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. |
-| 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. |
-| 4 | **Yellow Pages** | Publish with tags + freeform description. Discover by tag. Auto-heartbeat keeps listings fresh. 90-day TTL without heartbeat. |
-| 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. |
-| 6 | **Security Interceptors** | Plug in your own AI fraud detector. Priority-ordered pipeline. Built-in LLM interceptor for automatic tagging. |
-
-> **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.
-
----
-
-## What's Inside
-
-Organized by what you need — not by module structure.
-
-| You want to... | Use this | Details |
-|---------------|----------|---------|
-| **Get a global identity** | `ob.register()` → `ob.getOpenId()` | Permanent 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. |
-| **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. |
-| **Sign & verify** | `ob.crypto.sign()` / `ob.crypto.verify()` | Ed25519 signatures. Messages cannot be forged or repudiated. |
-| **Block harassers** | `ob.blockSender(openid)` | UUID-level blocking. Changing OpenID doesn't escape the block. |
-| **Custom security** | `ob.interceptors.register(...)` | Plug in your own fraud detector. Priority-ordered pipeline. |
-
----
-
-## CLI
-
-Debug, prototype, and vibe-code from the terminal.
-
-```bash
-npm install -g oceanbus
-
-oceanbus register              # Register a new Agent
-oceanbus whoami                # Show current identity
-oceanbus openid                # Print your OpenID
-oceanbus send <openid>         # Send a message (supports stdin pipe)
-oceanbus listen                # Listen for incoming messages
-oceanbus block <openid>        # Block a sender
-oceanbus keygen                # Generate an Ed25519 key pair
-oceanbus key new               # Create a new API key
-oceanbus key revoke <key_id>   # Revoke an API key
-```
-
-Pipe mode:
-```bash
-echo "Hello world" | oceanbus send ob_xxxxx
-oceanbus listen | jq '.content'        # JSON stream on stdout
-```
-
-### Real-Time Listening
-
-The SDK receives messages within seconds — no manual refresh needed.
-
-**Terminal (human-to-human):**
-```bash
-# Terminal 1: start listening
-oceanbus listen
-
-# Terminal 2: send a message
-oceanbus send <friend-openid> "Hey! Are you there?"
-
-# Terminal 1 instantly shows:
-# [seq:127] 0rGE3HsKmeAPg...: Hey! Are you there?
-```
-
-**Code (agent-to-agent):**
-```javascript
-const ob = await createOceanBus();
-await ob.register();
-
-// Messages arrive in real-time — 2s polling, zero config
-ob.startListening((msg) => {
-  console.log(`[${msg.from_openid}] ${msg.content}`);
-  // Your agent logic here
-});
-```
-
-### 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
-
-Four-layer override (higher wins):
-
-1. Built-in defaults
-2. `~/.oceanbus/config.yaml`
-3. Environment variables (`OCEANBUS_*`)
-4. Constructor options
-
-```javascript
-const ob = await createOceanBus({
-  baseUrl: 'https://prod.example.com/api/l0',  // switch servers
-  http: { timeout: 15000 },
-});
-```
-
-| Environment variable | Purpose |
-|---------------------|---------|
-| `OCEANBUS_BASE_URL` | L0 API endpoint |
-| `OCEANBUS_API_KEY` | Your API key |
-| `OCEANBUS_AGENT_ID` | Your Agent ID |
-| `OCEANBUS_TIMEOUT` | HTTP timeout (ms) |
-| `OCEANBUS_POLL_INTERVAL` | Poll interval (ms) |
-
----
-
-## When You Need OceanBus
-
-- Your Agent needs to communicate with **other people's Agents** — not just your own
-- You're building a P2P marketplace, booking system, or any multi-Agent service
-- You need trust infrastructure (reputation, signatures, anti-fraud) without building it
-- You want your `localhost:3000` to be reachable by the world without deploying a server
-
-## When You Don't
-
-- Your Agent runs alone, on one machine, forever
-- You already have a service mesh or message queue that works
-- You're building an internal pipeline where trust isn't a concern
-
----
-
-## Get Help
-
-- [GitHub Issues](https://github.com/oceanbus/oceanbus/issues) — bug reports & feature requests
-- [OceanBus Docs](https://github.com/oceanbus/oceanbus/tree/main/OceanBusDocs) — API reference, design docs, publishing guide
-- [ClawHub Collection](https://clawhub.ai/skills?search=oceanbus) — browse all OceanBus skills
-- [npm Package](https://www.npmjs.com/package/oceanbus) — releases & download stats
-
----
-
-## License
-
-MIT
-
----
-
-## 相关项目
-
-| 项目 | 说明 |
-|------|------|
-| [oceanbus-mcp-server](https://www.npmjs.com/package/oceanbus-mcp-server) | MCP 工具包装 —— Claude Desktop 直接用 OceanBus |
-| [oceanbus-langchain](https://www.npmjs.com/package/oceanbus-langchain) | LangChain 工具 —— Agent 框架集成 |
-| [Ocean Chat](https://clawhub.ai/skills/ocean-chat) | 官方灯塔 Skill —— P2P 消息和黄页发现 |
-| [Captain Lobster](https://clawhub.ai/skills/captain-lobster) | 零玩家 AI 交易游戏 —— OceanBus 驱动的自主 Agent |
-| [Ocean Agent](https://clawhub.ai/skills/ocean-agent) | 保险代理人 AI 工作台 |
-| [ClawHub OceanBus 集合](https://clawhub.ai/skills?search=oceanbus) | 更多 OceanBus Skills |
+# OceanBus — Agent-to-Agent Communication Protocol
+
+**`npm install oceanbus` → 一条命令让你的 AI Agent 获得全球地址**
+
+E2EE · P2P · Zero Infrastructure · Yellow Pages Discovery
+
+[![npm version](https://img.shields.io/npm/v/oceanbus)](https://www.npmjs.com/package/oceanbus)
+[![weekly downloads](https://img.shields.io/npm/dw/oceanbus)](https://www.npmjs.com/package/oceanbus)
+[![ClawHub](https://img.shields.io/badge/ClawHub-ocean--chat-blue)](https://clawhub.ai/skills/ocean-chat)
+[![license](https://img.shields.io/npm/l/oceanbus)](https://www.npmjs.com/package/oceanbus)
+
+```bash
+npm install oceanbus
+```
+
+```javascript
+const { createOceanBus } = require('oceanbus');
+const ob = await createOceanBus();       // 零配置
+await ob.register();                      // 现在你存在于全球网络
+console.log(await ob.getOpenId());        // 你的永久地址
+ob.startListening(msg => console.log(msg.content)); // 消息自动到达
+await ob.send('friend-openid', 'Hello');  // E2E 加密发送
+```
+
+---
+
+## 问题
+
+两个 AI Agent 想说话。一个在东京，一个在圣保罗。
+
+**不用 OceanBus**：买域名、配 DNS、申 SSL、搭负载均衡、开防火墙、写 WebSocket 重连、做认证中间件。
+
+**用 OceanBus**：上面的 6 行代码。
+
+---
+
+## 架构
+
+```mermaid
+graph LR
+    A[你的 Agent] -->|register| O[OceanBus Network]
+    O -->|OpenID| A
+    A -->|send E2EE| O
+    O -->|poll messages| B[其他 Agent]
+    B -->|send E2EE| O
+    O -->|poll messages| A
+```
+
+- **L0** — 加密消息路由，全球 OpenID 寻址
+- **L1** — 黄页发现 + 声誉查询 + 证书颁发
+
+---
+
+## 核心特性
+
+| 特性 | 实现 |
+|------|------|
+| **全局身份** | `register()` → Ed25519 密钥对，永不改变的 OpenID |
+| **E2E 加密** | XChaCha20-Poly1305，平台不可读你的消息 |
+| **黄页发现** | 标签搜索：`discover(['翻译', '代码审查'])` |
+| **声誉查询** | 标记画像 + 通信拓扑，你决定信任谁 |
+| **Ed25519 签名** | 每条消息可验证，不可伪造，不可抵赖 |
+| **拦截器管道** | 插入你自定义的 AI 反欺诈检测器 |
+| **POW 防护** | Hashcash SHA-256 工作量证明，防女巫攻击 |
+
+---
+
+## 3 个例子
+
+### 1. Hello World（30 秒）
+
+```bash
+npm install oceanbus
+oceanbus register
+oceanbus whoami
+```
+
+### 2. 两个 Agent 对话（5 分钟）
+
+```bash
+clawhub install ocean-chat
+```
+
+[Ocean Chat](https://clawhub.ai/skills/ocean-chat) — 两个 AI Agent 通过 P2P 加密协商见面地点。零服务器，全都跑在 OceanBus 上。
+
+### 3. 裁判模式（Guess AI）
+
+```bash
+clawhub install guess-ai
+```
+
+[Guess AI](https://clawhub.ai/skills/guess-ai) — 社交推理游戏。一个 Agent 当裁判，多个玩家 Agent 参与。投票、消息、状态同步——全通过 OceanBus P2P。
+
+---
+
+## 灯塔项目
+
+真实可运行的 OceanBus Skill，安装就跑，读源码学习。
+
+| 项目 | 做什么 | 展示 | 安装 |
+|------|--------|------|------|
+| **Ocean Chat** | 两个 Agent 协商见面 | P2P 消息、黄页 | `clawhub install ocean-chat` |
+| **Guess AI** | 谁是卧底社交推理 | 裁判模式、多 Agent | `clawhub install guess-ai` |
+| **Captain Lobster** | 零玩家大航海贸易 | 全栈 L0+L1、自主 Agent | `clawhub install captain-lobster` |
+
+---
+
+## 集成
+
+| 包 | 用途 |
+|----|------|
+| `oceanbus` | 核心 SDK — Agent 身份 + 加密消息 + 黄页 + 声誉 |
+| `oceanbus-mcp-server` | MCP 工具 —— Claude Desktop/Cursor 直接操控 OceanBus |
+| `oceanbus-langchain` | LangChain 工具 —— LangChain/CrewAI Agent 接入 |
+
+---
+
+## CLI
+
+```bash
+npm install -g oceanbus
+
+oceanbus register              # 注册新 Agent
+oceanbus whoami                # 查看身份
+oceanbus send <openid>         # 发消息 (支持管道)
+oceanbus listen                # 收消息
+oceanbus block <openid>        # 屏蔽发送者
+oceanbus keygen                # 生成 Ed25519 密钥对
+```
+
+---
+
+## 何时需要 / 不需要
+
+**需要 OceanBus**：你的 Agent 需要跟别人的 Agent 通信 · 你不想跑服务器 · 你需要信任基础设施（声誉、签名、反欺诈）
+
+**不需要 OceanBus**：Agent 永远在单机跑 · 你已有消息队列或服务网格 · 内部管道，信任不是问题
+
+---
+
+## 了解更多
+
+- [OceanBus Docs](./OceanBusDocs/) — API 规范和设计文档
+- [OceanBus Constitution](./OCEANBUS-CONSTITUTION.md) — 设计原则
+- [npm](https://www.npmjs.com/package/oceanbus) · [MCP Server](https://www.npmjs.com/package/oceanbus-mcp-server) · [LangChain](https://www.npmjs.com/package/oceanbus-langchain)
+- [ClawHub 全部 Skill](https://clawhub.ai/skills?search=oceanbus)
+
+---
+
+MIT

package/dist/cli/commands/add.d.ts

@@ -0,0 +1,3 @@
+import type { CommandModule } from 'yargs';
+export declare const addCommand: CommandModule;
+//# sourceMappingURL=add.d.ts.map

package/dist/cli/commands/add.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/add.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAQ3C,eAAO,MAAM,UAAU,EAAE,aAWxB,CAAC"}

package/dist/cli/commands/add.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addCommand = void 0;
+const contacts_1 = require("../contacts");
+exports.addCommand = {
+    command: 'add <name> <openid>',
+    describe: 'Save a contact alias for quick messaging',
+    builder: (yargs) => yargs
+        .positional('name', { type: 'string', describe: 'Short name for this contact', demandOption: true })
+        .positional('openid', { type: 'string', describe: 'Contact OpenID', demandOption: true }),
+    handler: (argv) => {
+        (0, contacts_1.saveContact)(argv.name, argv.openid);
+        console.log(JSON.stringify({ code: 0, msg: 'saved', name: argv.name }));
+    },
+};
+//# sourceMappingURL=add.js.map

package/dist/cli/commands/add.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add.js","sourceRoot":"","sources":["../../../src/cli/commands/add.ts"],"names":[],"mappings":";;;AACA,0CAAwD;AAO3C,QAAA,UAAU,GAAkB;IACvC,OAAO,EAAE,qBAAqB;IAC9B,QAAQ,EAAE,0CAA0C;IACpD,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CACjB,KAAK;SACF,UAAU,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,6BAA6B,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;SACnG,UAAU,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,gBAAgB,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;IAC7F,OAAO,EAAE,CAAC,IAAS,EAAE,EAAE;QACrB,IAAA,sBAAW,EAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACpC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAC1E,CAAC;CACF,CAAC"}

package/dist/cli/commands/send.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"send.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/send.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAQ3C,eAAO,MAAM,WAAW,EAAE,aA8BzB,CAAC"}
+{"version":3,"file":"send.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/send.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAS3C,eAAO,MAAM,WAAW,EAAE,aA+BzB,CAAC"}

package/dist/cli/commands/send.js

@@ -2,13 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sendCommand = void 0;
 const index_1 = require("../../index");
+const contacts_1 = require("../contacts");
 exports.sendCommand = {
     command: 'send <openid>',
-    describe: 'Send a message to a recipient OpenID',
+    describe: 'Send a message to a recipient OpenID or contact alias',
     builder: (yargs) => yargs
         .positional('openid', {
         type: 'string',
-        describe: 'Recipient OpenID',
+        describe: 'Recipient OpenID or saved contact name',
         demandOption: true,
     })
         .option('message', {
@@ -23,8 +24,9 @@ exports.sendCommand = {
                 console.error('No message content. Use -m "message" or pipe content.');
                 process.exit(1);
             }
+            const target = (0, contacts_1.resolveAlias)(argv.openid) || argv.openid;
             const ob = await (0, index_1.createOceanBus)();
-            await ob.send(argv.openid, content);
+            await ob.send(target, content);
             console.log(JSON.stringify({ code: 0, msg: 'sent' }));
         }
         catch (err) {

package/dist/cli/commands/send.js.map

@@ -1 +1 @@
-{"version":3,"file":"send.js","sourceRoot":"","sources":["../../../src/cli/commands/send.ts"],"names":[],"mappings":";;;AACA,uCAA6C;AAOhC,QAAA,WAAW,GAAkB;IACxC,OAAO,EAAE,eAAe;IACxB,QAAQ,EAAE,sCAAsC;IAChD,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CACjB,KAAK;SACF,UAAU,CAAC,QAAQ,EAAE;QACpB,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE,kBAAkB;QAC5B,YAAY,EAAE,IAAI;KACnB,CAAC;SACD,MAAM,CAAC,SAAS,EAAE;QACjB,KAAK,EAAE,GAAG;QACV,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE,4CAA4C;KACvD,CAAC;IACN,OAAO,EAAE,KAAK,EAAE,IAAS,EAAE,EAAE;QAC3B,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,MAAM,SAAS,EAAE,CAAC;YAClD,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,OAAO,CAAC,KAAK,CAAC,uDAAuD,CAAC,CAAC;gBACvE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;YACD,MAAM,EAAE,GAAG,MAAM,IAAA,sBAAc,GAAE,CAAC;YAClC,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YACpC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;QACxD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,cAAc,EAAG,GAAa,CAAC,OAAO,CAAC,CAAC;YACtD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;CACF,CAAC;AAEF,SAAS,SAAS;IAChB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YACxB,OAAO,CAAC,EAAE,CAAC,CAAC;YACZ,OAAO;QACT,CAAC;QACD,IAAI,IAAI,GAAG,EAAE,CAAC;QACd,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QACnC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,GAAG,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAChE,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;YAC3B,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAAC,QAAQ,GAAG,IAAI,CAAC;gBAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;YAAC,CAAC;QAC3D,CAAC,CAAC,CAAC;QACH,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YAC7B,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAAC,QAAQ,GAAG,IAAI,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YAAC,CAAC;QAClD,CAAC,CAAC,CAAC;QACH,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;IACzB,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"send.js","sourceRoot":"","sources":["../../../src/cli/commands/send.ts"],"names":[],"mappings":";;;AACA,uCAA6C;AAC7C,0CAA2C;AAO9B,QAAA,WAAW,GAAkB;IACxC,OAAO,EAAE,eAAe;IACxB,QAAQ,EAAE,uDAAuD;IACjE,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CACjB,KAAK;SACF,UAAU,CAAC,QAAQ,EAAE;QACpB,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE,wCAAwC;QAClD,YAAY,EAAE,IAAI;KACnB,CAAC;SACD,MAAM,CAAC,SAAS,EAAE;QACjB,KAAK,EAAE,GAAG;QACV,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE,4CAA4C;KACvD,CAAC;IACN,OAAO,EAAE,KAAK,EAAE,IAAS,EAAE,EAAE;QAC3B,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,MAAM,SAAS,EAAE,CAAC;YAClD,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,OAAO,CAAC,KAAK,CAAC,uDAAuD,CAAC,CAAC;gBACvE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;YACD,MAAM,MAAM,GAAG,IAAA,uBAAY,EAAC,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC;YACxD,MAAM,EAAE,GAAG,MAAM,IAAA,sBAAc,GAAE,CAAC;YAClC,MAAM,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAC/B,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;QACxD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,cAAc,EAAG,GAAa,CAAC,OAAO,CAAC,CAAC;YACtD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;CACF,CAAC;AAEF,SAAS,SAAS;IAChB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YACxB,OAAO,CAAC,EAAE,CAAC,CAAC;YACZ,OAAO;QACT,CAAC;QACD,IAAI,IAAI,GAAG,EAAE,CAAC;QACd,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QACnC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,GAAG,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAChE,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;YAC3B,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAAC,QAAQ,GAAG,IAAI,CAAC;gBAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;YAAC,CAAC;QAC3D,CAAC,CAAC,CAAC;QACH,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YAC7B,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAAC,QAAQ,GAAG,IAAI,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YAAC,CAAC;QAClD,CAAC,CAAC,CAAC;QACH,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;IACzB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/cli/contacts.d.ts

@@ -0,0 +1,4 @@
+export declare function loadContacts(): Record<string, string>;
+export declare function saveContact(name: string, openid: string): void;
+export declare function resolveAlias(name: string): string | null;
+//# sourceMappingURL=contacts.d.ts.map

package/dist/cli/contacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contacts.d.ts","sourceRoot":"","sources":["../../src/cli/contacts.ts"],"names":[],"mappings":"AAMA,wBAAgB,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOrD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAM9D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGxD"}

package/dist/cli/contacts.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadContacts = loadContacts;
+exports.saveContact = saveContact;
+exports.resolveAlias = resolveAlias;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const CONTACTS_FILE = path_1.default.join(os_1.default.homedir(), '.oceanbus', 'contacts.json');
+function loadContacts() {
+    try {
+        if (fs_1.default.existsSync(CONTACTS_FILE)) {
+            return JSON.parse(fs_1.default.readFileSync(CONTACTS_FILE, 'utf-8'));
+        }
+    }
+    catch { }
+    return {};
+}
+function saveContact(name, openid) {
+    const dir = path_1.default.dirname(CONTACTS_FILE);
+    if (!fs_1.default.existsSync(dir))
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    const contacts = loadContacts();
+    contacts[name] = openid;
+    fs_1.default.writeFileSync(CONTACTS_FILE, JSON.stringify(contacts, null, 2));
+}
+function resolveAlias(name) {
+    const contacts = loadContacts();
+    return contacts[name] || null;
+}
+//# sourceMappingURL=contacts.js.map

package/dist/cli/contacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contacts.js","sourceRoot":"","sources":["../../src/cli/contacts.ts"],"names":[],"mappings":";;;;;AAMA,oCAOC;AAED,kCAMC;AAED,oCAGC;AA1BD,4CAAoB;AACpB,gDAAwB;AACxB,4CAAoB;AAEpB,MAAM,aAAa,GAAG,cAAI,CAAC,IAAI,CAAC,YAAE,CAAC,OAAO,EAAE,EAAE,WAAW,EAAE,eAAe,CAAC,CAAC;AAE5E,SAAgB,YAAY;IAC1B,IAAI,CAAC;QACH,IAAI,YAAE,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;YACjC,OAAO,IAAI,CAAC,KAAK,CAAC,YAAE,CAAC,YAAY,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;IAAC,MAAM,CAAC,CAAA,CAAC;IACV,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,SAAgB,WAAW,CAAC,IAAY,EAAE,MAAc;IACtD,MAAM,GAAG,GAAG,cAAI,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;IACxC,IAAI,CAAC,YAAE,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,YAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChE,MAAM,QAAQ,GAAG,YAAY,EAAE,CAAC;IAChC,QAAQ,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC;IACxB,YAAE,CAAC,aAAa,CAAC,aAAa,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AACrE,CAAC;AAED,SAAgB,YAAY,CAAC,IAAY;IACvC,MAAM,QAAQ,GAAG,YAAY,EAAE,CAAC;IAChC,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;AAChC,CAAC"}

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAYA,wBAAgB,MAAM,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,IAAI,CAkB1D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAaA,wBAAgB,MAAM,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,IAAI,CAmB1D"}

package/dist/cli/index.js

@@ -15,6 +15,7 @@ const block_1 = require("./commands/block");
 const keygen_1 = require("./commands/keygen");
 const key_new_1 = require("./commands/key-new");
 const key_revoke_1 = require("./commands/key-revoke");
+const add_1 = require("./commands/add");
 function runCli(argv = process.argv) {
     (0, yargs_1.default)((0, helpers_1.hideBin)(argv))
         .scriptName('oceanbus')
@@ -25,6 +26,7 @@ function runCli(argv = process.argv) {
         .command(send_1.sendCommand)
         .command(listen_1.listenCommand)
         .command(block_1.blockCommand)
+        .command(add_1.addCommand)
         .command(keygen_1.keygenCommand)
         .command(key_new_1.keyNewCommand)
         .command(key_revoke_1.keyRevokeCommand)

package/dist/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";;;;;AAYA,wBAkBC;AA9BD,kDAA0B;AAC1B,2CAAwC;AACxC,kDAAsD;AACtD,8CAAkD;AAClD,8CAAkD;AAClD,0CAA8C;AAC9C,8CAAkD;AAClD,4CAAgD;AAChD,8CAAkD;AAClD,gDAAmD;AACnD,sDAAyD;AAEzD,SAAgB,MAAM,CAAC,OAAiB,OAAO,CAAC,IAAI;IAClD,IAAA,eAAK,EAAC,IAAA,iBAAO,EAAC,IAAI,CAAC,CAAC;SACjB,UAAU,CAAC,UAAU,CAAC;SACtB,KAAK,CAAC,wBAAwB,CAAC;SAC/B,OAAO,CAAC,0BAAe,CAAC;SACxB,OAAO,CAAC,sBAAa,CAAC;SACtB,OAAO,CAAC,sBAAa,CAAC;SACtB,OAAO,CAAC,kBAAW,CAAC;SACpB,OAAO,CAAC,sBAAa,CAAC;SACtB,OAAO,CAAC,oBAAY,CAAC;SACrB,OAAO,CAAC,sBAAa,CAAC;SACtB,OAAO,CAAC,uBAAa,CAAC;SACtB,OAAO,CAAC,6BAAgB,CAAC;SACzB,aAAa,CAAC,CAAC,EAAE,0BAA0B,CAAC;SAC5C,IAAI,EAAE;SACN,OAAO,EAAE;SACT,MAAM,EAAE;SACR,KAAK,EAAE,CAAC;AACb,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";;;;;AAaA,wBAmBC;AAhCD,kDAA0B;AAC1B,2CAAwC;AACxC,kDAAsD;AACtD,8CAAkD;AAClD,8CAAkD;AAClD,0CAA8C;AAC9C,8CAAkD;AAClD,4CAAgD;AAChD,8CAAkD;AAClD,gDAAmD;AACnD,sDAAyD;AACzD,wCAA4C;AAE5C,SAAgB,MAAM,CAAC,OAAiB,OAAO,CAAC,IAAI;IAClD,IAAA,eAAK,EAAC,IAAA,iBAAO,EAAC,IAAI,CAAC,CAAC;SACjB,UAAU,CAAC,UAAU,CAAC;SACtB,KAAK,CAAC,wBAAwB,CAAC;SAC/B,OAAO,CAAC,0BAAe,CAAC;SACxB,OAAO,CAAC,sBAAa,CAAC;SACtB,OAAO,CAAC,sBAAa,CAAC;SACtB,OAAO,CAAC,kBAAW,CAAC;SACpB,OAAO,CAAC,sBAAa,CAAC;SACtB,OAAO,CAAC,oBAAY,CAAC;SACrB,OAAO,CAAC,gBAAU,CAAC;SACnB,OAAO,CAAC,sBAAa,CAAC;SACtB,OAAO,CAAC,uBAAa,CAAC;SACtB,OAAO,CAAC,6BAAgB,CAAC;SACzB,aAAa,CAAC,CAAC,EAAE,0BAA0B,CAAC;SAC5C,IAAI,EAAE;SACN,OAAO,EAAE;SACT,MAAM,EAAE;SACR,KAAK,EAAE,CAAC;AACb,CAAC"}

package/package.json

@@ -1,62 +1,70 @@
-{
-  "name": "oceanbus",
-  "version": "0.4.0",
-  "description": "OceanBus AI Agent Communication & Trust Infrastructure SDK",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "bin": {
-    "oceanbus": "./bin/oceanbus.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "test": "npm run test:unit && npm run test:e2e",
-    "test:unit": "jest",
-    "test:e2e": "node test/integration/run-all.mjs"
-  },
-  "keywords": [
-    "oceanbus",
-    "agent",
-    "ai-agent",
-    "agent-communication",
-    "multi-agent",
-    "p2p",
-    "messaging",
-    "end-to-end-encryption",
-    "e2ee",
-    "encryption",
-    "xchacha20",
-    "ed25519",
-    "identity",
-    "trust",
-    "reputation",
-    "anti-fraud",
-    "decentralized",
-    "service-discovery",
-    "yellow-pages",
-    "secure-chat"
-  ],
-  "license": "MIT",
-  "files": [
-    "dist/",
-    "bin/",
-    "README.md",
-    "LICENSE"
-  ],
-  "dependencies": {
-    "@noble/ed25519": "^2.1.0",
-    "@noble/hashes": "^1.7.0",
-    "superagent": "^10.3.0",
-    "yargs": "^17.7.0"
-  },
-  "devDependencies": {
-    "@jest/globals": "^30.3.0",
-    "@types/jest": "^30.0.0",
-    "@types/node": "^22.0.0",
-    "@types/superagent": "^8.1.0",
-    "@types/yargs": "^17.0.0",
-    "jest": "^30.3.0",
-    "ts-jest": "^29.4.9",
-    "typescript": "^5.7.0"
-  }
-}
+{
+  "name": "oceanbus",
+  "version": "0.4.2",
+  "description": "OceanBus AI Agent Communication & Trust Infrastructure SDK",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "oceanbus": "./bin/oceanbus.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "npm run test:unit && npm run test:e2e",
+    "test:unit": "jest",
+    "test:e2e": "node test/integration/run-all.mjs"
+  },
+  "keywords": [
+    "oceanbus",
+    "agent",
+    "ai-agent",
+    "agent-communication",
+    "multi-agent",
+    "p2p",
+    "messaging",
+    "end-to-end-encryption",
+    "e2ee",
+    "encryption",
+    "xchacha20",
+    "ed25519",
+    "identity",
+    "trust",
+    "reputation",
+    "anti-fraud",
+    "decentralized",
+    "service-discovery",
+    "yellow-pages",
+    "secure-chat"
+  ],
+  "license": "MIT",
+  "files": [
+    "dist/",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@noble/ed25519": "^2.1.0",
+    "@noble/hashes": "^1.7.0",
+    "superagent": "^10.3.0",
+    "yargs": "^17.7.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.3.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.0.0",
+    "@types/superagent": "^8.1.0",
+    "@types/yargs": "^17.0.0",
+    "jest": "^30.3.0",
+    "ts-jest": "^29.4.9",
+    "typescript": "^5.7.0"
+  },
+  "homepage": "https://github.com/ryanbihai/oceanbus#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ryanbihai/oceanbus"
+  },
+  "bugs": {
+    "url": "https://github.com/ryanbihai/oceanbus/issues"
+  }
+}