libp2p-mesh 2026.5.31 → 2026.6.1

package/README.md

@@ -1,4 +1,4 @@
-# openclaw-libp2p-mesh
+# libp2p-mesh
 
 P2P mesh network plugin for OpenClaw. Enables direct peer-to-peer communication between OpenClaw instances using libp2p — no central server required.
 
@@ -22,7 +22,7 @@ P2P mesh network plugin for OpenClaw. Enables direct peer-to-peer communication
 ### Method 1: Via OpenClaw CLI (Recommended)
 
 ```bash
-openclaw install openclaw-libp2p-mesh
+openclaw install libp2p-mesh
 ```
 
 ### Method 2: Manual (npm)
@@ -31,7 +31,7 @@ openclaw install openclaw-libp2p-mesh
 
 ```bash
 cd ~/.openclaw/npm
-npm install openclaw-libp2p-mesh
+npm install libp2p-mesh
 ```
 
 然后刷新插件注册表：
@@ -42,9 +42,7 @@ openclaw plugins registry --refresh
 
 The published npm package includes compiled JavaScript under `dist/`, so OpenClaw and acpx can load it directly.
 
-After installing the plugin, you must:
-
-1. **Enable the plugin** in `~/.openclaw/openclaw.json`:
+Then add to your `~/.openclaw/openclaw.json`:
 
 ```json
 {
@@ -64,78 +62,6 @@ After installing the plugin, you must:
 }
 ```
 
-2. **Set `tools.profile` to `full`** — OpenClaw defaults to `"coding"` profile, which **filters out** P2P tools. Even if you add them to `tools.allow`, the coding profile will still block them. You must change to `"full"` first:
-
-```json
-{
-  "tools": {
-    "profile": "full",
-    "allow": [
-      "p2p_list_peers",
-      "p2p_send_message",
-      "p2p_broadcast"
-    ]
-  }
-}
-```
-
-> **Why `profile: "full"`?** The `"coding"` profile hardcodes a deny list that includes `p2p_list_peers`, `p2p_send_message`, and `p2p_broadcast`. With `profile: "coding"`, adding tools to `tools.allow` has no effect for these three — the profile filter runs first and removes them.
-
-3. **Restart the gateway:**
-
-```bash
-openclaw gateway restart
-```
-
-4. **Verify tool registration:**
-
-```bash
-openclaw plugins inspect libp2p-mesh --runtime --json | jq '.plugin.toolNames, .tools'
-```
-
-Expected output:
-```json
-[
-  "p2p_send_message",
-  "p2p_broadcast",
-  "p2p_list_peers",
-  "p2p_get_instance_identity",
-  "p2p_get_network_info"
-]
-```
-
-### One-command setup (optional)
-
-Instead of manually editing `openclaw.json`, run:
-
-```bash
-npx openclaw-libp2p-mesh-configure-tools
-# or, from the plugin directory:
-npm run configure-tools
-```
-
-This patches `~/.openclaw/openclaw.json` with the correct `tools.profile` and `tools.allow` values. Use `--check` to preview without modifying:
-
-```bash
-npm run configure-tools:check
-```
-
-## Troubleshooting
-
-### "plugin must declare contracts.tools before registering agent tools"
-
-Make sure you are running **OpenClaw >= 2026.6.5** and the plugin is installed via `openclaw install` or `npm install` into `~/.openclaw/npm`. The manifest (`openclaw.plugin.json`) ships with `contracts.tools` pre-declared, so no manual manifest edits are needed.
-
-### Tools still not available after setup
-
-1. Confirm `tools.profile` is `"full"` (not `"coding"`):
-   ```bash
-   cat ~/.openclaw/openclaw.json | jq '.tools'
-   ```
-2. Confirm all three P2P tools are in `tools.allow`.
-3. Restart the gateway (not just reload).
-4. Check `openclaw plugins inspect libp2p-mesh --runtime --json` for diagnostics.
-
 ## Configuration
 
 Add a `libp2p-mesh` block to your `openclaw.json` under `plugins`:
@@ -214,7 +140,7 @@ If peers are on different networks, use a bootstrap node:
 
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
-| `discovery` | `string` | `"mdns"` | Discovery mechanism: `"mdns"` (LAN), `"bootstrap"` (static list), `"dht"` (not yet implemented) |
+| `discovery` | `string` | `"mdns"` | Discovery mechanism: `"mdns"` (LAN), `"bootstrap"` (static list), `"dht"` (Kademlia peer discovery and pubkey registry) |
 | `listenAddrs` | `string[]` | `["/ip4/0.0.0.0/tcp/0"]` | libp2p listen multiaddrs |
 | `bootstrapList` | `string[]` | `[]` | Static bootstrap peer multiaddrs (when `discovery=bootstrap`) |
 | `enableWebSocket` | `boolean` | `false` | Enable WebSocket transport for browser/NAT compatibility |
@@ -230,6 +156,9 @@ If peers are on different networks, use a bootstrap node:
 | `relayList` | `string[]` | `[]` | Multiaddrs of relays to reserve a slot on |
 | `discoverRelays` | `number` | `0` | Auto-discover this many relays via content routing |
 | `announceAddrs` | `string[]` | `[]` | Extra multiaddrs to announce on top of auto-detected ones |
+| `inboundChannel` | `string` | `undefined` | OpenClaw channel used to display inbound P2P user messages, for example `"feishu"` |
+| `inboundTarget` | `string` | `undefined` | OpenClaw channel target for inbound P2P messages, for example `user:ou_xxx` or `chat:oc_xxx` |
+| `deliveryAckTimeoutMs` | `number` | `15000` | Timeout for waiting on remote channel delivery ACKs |
 
 ## NAT Traversal
 
@@ -342,6 +271,53 @@ Check the gateway logs on the receiving machine. You should see:
 [libp2p-mesh] Direct message from <sender-peer-id>: Hello from A!
 ```
 
+## Sending by OpenClaw Instance ID
+
+When two gateways connect, `libp2p-mesh` exchanges instance route announcements and automatically writes:
+
+```text
+~/.openclaw/libp2p/instance-peer.json
+```
+
+When `OPENCLAW_STATE_DIR` is set, the file is written to:
+
+```text
+$OPENCLAW_STATE_DIR/libp2p/instance-peer.json
+```
+
+Users do not configure this file path. It is plugin-managed state.
+
+For Feishu inbound display, configure the receiving instance:
+
+```json
+{
+  "plugins": {
+    "libp2p-mesh": {
+      "enabled": true,
+      "config": {
+        "discovery": "mdns",
+        "inboundChannel": "feishu",
+        "inboundTarget": "user:ou_xxx",
+        "deliveryAckTimeoutMs": 15000
+      }
+    }
+  },
+  "channels": {
+    "libp2p-mesh": { "enabled": true }
+  }
+}
+```
+
+The OpenClaw agent should prefer:
+
+```text
+p2p_send_instance_message({ "instanceId": "<target-instance-id>", "message": "今晚出来吃饭" })
+```
+
+The sender reports success only after the remote OpenClaw instance forwards the message to its configured inbound channel and returns a delivery ACK.
+
+Tools are not configured in `openclaw.json`; they are registered automatically by the plugin through `api.registerTool()`.
+
 ## Troubleshooting
 
 ### Peers do not discover each other
@@ -380,6 +356,17 @@ The peer may be unreachable. Check:
 - Are both machines on the same network?
 - Is there a firewall blocking the connection?
 
+### Connected peers are not visible in logs
+
+Peer connection and disconnection are logged at `info` level:
+
+```text
+[libp2p-mesh] Peer connected: 12D3KooW...
+[libp2p-mesh] Instance mapping updated: bob@def.456 -> 12D3KooW...
+```
+
+If these lines are missing, confirm the gateway is running with normal info logs enabled and that both instances are on the same mDNS, bootstrap, or relay network.
+
 ## Architecture
 
 ```

package/api.ts

@@ -1,2 +1,20 @@
 export { createMeshNetwork } from "./src/mesh.js";
-export type { MeshNetwork, P2PMessage, MeshConfig, InstanceIdentity } from "./src/types.js";
+export { createInstancePeerStore } from "./src/instance-peer-store.js";
+export { createInstanceRouter } from "./src/instance-router.js";
+export type {
+  DeliveryAckPayload,
+  InboundDeliveryAdapter,
+  InboundDeliveryRequest,
+  InboundDeliveryResult,
+  InstanceAnnouncePayload,
+  InstanceIdentity,
+  InstancePeerRecord,
+  InstancePeerStore,
+  InstancePeerTable,
+  InstanceRouter,
+  MeshConfig,
+  MeshNetwork,
+  P2PMessage,
+  P2PMessageType,
+  UserMessagePayload,
+} from "./src/types.js";

package/dist/api.d.ts

@@ -1,2 +1,4 @@
 export { createMeshNetwork } from "./src/mesh.js";
-export type { MeshNetwork, P2PMessage, MeshConfig, InstanceIdentity } from "./src/types.js";
+export { createInstancePeerStore } from "./src/instance-peer-store.js";
+export { createInstanceRouter } from "./src/instance-router.js";
+export type { DeliveryAckPayload, InboundDeliveryAdapter, InboundDeliveryRequest, InboundDeliveryResult, InstanceAnnouncePayload, InstanceIdentity, InstancePeerRecord, InstancePeerStore, InstancePeerTable, InstanceRouter, MeshConfig, MeshNetwork, P2PMessage, P2PMessageType, UserMessagePayload, } from "./src/types.js";

package/dist/api.js

@@ -1 +1,3 @@
 export { createMeshNetwork } from "./src/mesh.js";
+export { createInstancePeerStore } from "./src/instance-peer-store.js";
+export { createInstanceRouter } from "./src/instance-router.js";

package/dist/index.d.ts

@@ -1,3 +1,9 @@
-import { definePluginEntry } from "openclaw/plugin-sdk/core";
-declare const _default: ReturnType<typeof definePluginEntry>;
+import type { OpenClawPluginConfigSchema } from "openclaw/plugin-sdk/core";
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: OpenClawPluginConfigSchema;
+    register: NonNullable<import("openclaw/plugin-sdk/core").OpenClawPluginDefinition["register"]>;
+} & Pick<import("openclaw/plugin-sdk/core").OpenClawPluginDefinition, "reload" | "kind" | "nodeHostCommands" | "securityAuditCollectors">;
 export default _default;

package/dist/index.js

@@ -109,6 +109,19 @@ function createLibp2pMeshConfigSchema() {
                     items: { type: "string" },
                     description: "Extra multiaddrs to announce to the network (useful when running behind a known port forward where AutoNAT cannot probe).",
                 },
+                inboundChannel: {
+                    type: "string",
+                    description: "OpenClaw channel used to display inbound P2P user messages, for example \"feishu\".",
+                },
+                inboundTarget: {
+                    type: "string",
+                    description: "OpenClaw channel target for inbound P2P user messages, for example user:ou_xxx or chat:oc_xxx.",
+                },
+                deliveryAckTimeoutMs: {
+                    type: "number",
+                    default: 15000,
+                    description: "How long p2p_send_instance_message waits for a remote delivery ACK.",
+                },
             },
         },
     };