libp2p-mesh 2026.6.9 → 2026.6.11

package/README.md

@@ -42,66 +42,78 @@ openclaw plugins registry --refresh
 
 The published npm package includes compiled JavaScript under `dist/`, so OpenClaw and acpx can load it directly.
 
-## Configuration
-
-### Quick Setup (Recommended)
-
-After installation, run the interactive setup wizard:
+Then run the setup wizard:
 
 ```bash
 openclaw libp2p-mesh setup
 ```
 
-The wizard will guide you through:
-- Discovery mode (mDNS / Bootstrap / DHT)
-- Bootstrap peer addresses (for cross-network scenarios)
-- Inbound channel targets (where to display received P2P messages)
-- Optional: NAT traversal, circuit relay, fixed ports, and custom instance name
-
-The configuration is written to `~/.openclaw/openclaw.json` automatically.
+The wizard creates or edits `plugins.entries["libp2p-mesh"].config` in your OpenClaw config file. You do not need to manually edit `openclaw.json`.
 
-### Incremental Config Management
+After the wizard writes changes, restart the gateway:
 
 ```bash
-# View all current non-default settings
-openclaw libp2p-mesh config list
+openclaw gateway restart
+```
 
-# Read a single value
-openclaw libp2p-mesh config get discovery
+The generated config shape is:
 
-# Set a value
-openclaw libp2p-mesh config set discovery bootstrap
+```json
+{
+  "plugins": {
+    "entries": {
+      "libp2p-mesh": {
+        "enabled": true,
+        "config": {
+          "discovery": "mdns",
+          "deliveryAckTimeoutMs": 15000
+        }
+      }
+    }
+  }
+}
+```
 
-# Add to an array
-openclaw libp2p-mesh config set bootstrapList --add /ip4/10.0.0.5/tcp/4001/p2p/12D3KooW...
+## Configuration
 
-# Remove from an array
-openclaw libp2p-mesh config set bootstrapList --remove /ip4/203.0.113.10/tcp/4001/p2p/12D3KooW...
+Use the interactive setup command for first-time configuration and later edits:
 
-# Reset a key to default
-openclaw libp2p-mesh config unset relayList
+```bash
+openclaw libp2p-mesh setup
 ```
 
-### Manual Configuration (Advanced)
+On first run, the wizard enables the plugin and writes `plugins.entries["libp2p-mesh"].config`. On later runs, it edits the existing `libp2p-mesh` entry instead of replacing it blindly. It can update the network mode, add or remove inbound delivery targets, preview the final JSON, and only writes after you confirm.
+
+The wizard uses OpenClaw's config writer, so the actual file is your normal OpenClaw config path, usually `~/.openclaw/openclaw.json`. You do not need to manually edit `openclaw.json`, and the wizard does not create `channels["libp2p-mesh"]`.
 
-You can still directly edit `~/.openclaw/openclaw.json`:
+Restart the gateway after applying changes:
+
+```bash
+openclaw gateway restart
+```
 
 ### Minimal LAN Setup (Default)
 
+Run:
+
+```bash
+openclaw libp2p-mesh setup
+```
+
+Choose LAN mode for two computers on the same WiFi or Ethernet segment. The wizard writes:
+
 ```json
 {
   "plugins": {
-    "libp2p-mesh": {
-      "enabled": true,
-      "config": {
-        "discovery": "mdns"
+    "entries": {
+      "libp2p-mesh": {
+        "enabled": true,
+        "config": {
+          "discovery": "mdns",
+          "deliveryAckTimeoutMs": 15000
+        }
       }
     }
-  },
-  "channels": {
-    "libp2p-mesh": {
-      "enabled": true
-    }
   }
 }
 ```
@@ -115,47 +127,83 @@ By default, the node picks a random TCP port. To use a fixed port:
 ```json
 {
   "plugins": {
-    "libp2p-mesh": {
-      "enabled": true,
-      "config": {
-        "discovery": "mdns",
-        "listenAddrs": ["/ip4/0.0.0.0/tcp/4001"]
+    "entries": {
+      "libp2p-mesh": {
+        "enabled": true,
+        "config": {
+          "discovery": "mdns",
+          "listenAddrs": ["/ip4/0.0.0.0/tcp/4001"],
+          "deliveryAckTimeoutMs": 15000
+        }
       }
     }
-  },
-  "channels": {
-    "libp2p-mesh": {
-      "enabled": true
-    }
   }
 }
 ```
 
 ### With Bootstrap Nodes (Cross-Network)
 
-If peers are on different networks, use a bootstrap node:
+If peers are on different networks, run the setup wizard and choose cross-network mode. It prompts for bootstrap and optional relay multiaddrs, then writes:
 
 ```json
 {
   "plugins": {
-    "libp2p-mesh": {
-      "enabled": true,
-      "config": {
-        "discovery": "bootstrap",
-        "bootstrapList": [
-          "/ip4/203.0.113.10/tcp/4001/p2p/12D3KooW..."
-        ]
+    "entries": {
+      "libp2p-mesh": {
+        "enabled": true,
+        "config": {
+          "discovery": "bootstrap",
+          "bootstrapList": [
+            "/ip4/203.0.113.10/tcp/4001/p2p/12D3KooW..."
+          ],
+          "relayList": [
+            "/ip4/203.0.113.10/tcp/4001/p2p/12D3KooW..."
+          ],
+          "enableNATTraversal": true,
+          "deliveryAckTimeoutMs": 15000
+        }
       }
     }
-  },
-  "channels": {
-    "libp2p-mesh": {
-      "enabled": true
+  }
+}
+```
+
+### Multiple Inbound Targets
+
+Inbound delivery is owned by the receiving OpenClaw instance. In the setup wizard, choose to add one or more inbound delivery targets. The sender still sends to the receiver's peer ID or instance ID; the receiver decides which local channels display the incoming message.
+
+Example wizard output with two targets:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "libp2p-mesh": {
+        "enabled": true,
+        "config": {
+          "discovery": "mdns",
+          "inboundTargets": [
+            {
+              "id": "feishu-main",
+              "channel": "feishu",
+              "target": "user:ou_xxx"
+            },
+            {
+              "id": "telegram-main",
+              "channel": "telegram",
+              "target": "chat:123456"
+            }
+          ],
+          "deliveryAckTimeoutMs": 15000
+        }
+      }
     }
   }
 }
 ```
 
+If `inboundTargets` is an empty array, inbound delivery is disabled. If `inboundTargets` is omitted, the plugin keeps any existing inbound behavior unchanged. When `inboundTargets` is present, it overrides legacy `inboundChannel`/`inboundTarget`.
+
 ### Full Configuration Reference
 
 | Key | Type | Default | Description |
@@ -178,7 +226,7 @@ If peers are on different networks, use a bootstrap node:
 | `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` |
-| `inboundTargets` | `{ id?: string, channel: string, target: string }[]` | `undefined` | Receiver-owned list of channel targets for inbound P2P user messages. When present, overrides `inboundChannel`/`inboundTarget`; an empty array disables inbound delivery |
+| `inboundTargets` | `array` | `undefined` | Optional list of receiver-owned channel targets for inbound P2P user messages. When present, it overrides `inboundChannel`/`inboundTarget`; an empty array disables inbound delivery. |
 | `deliveryAckTimeoutMs` | `number` | `15000` | Timeout for waiting on remote channel delivery ACKs |
 
 ## NAT Traversal
@@ -197,16 +245,20 @@ You need at least one relay node with a public IP. Set it in `relayList`:
 ```json
 {
   "plugins": {
-    "libp2p-mesh": {
-      "enabled": true,
-      "config": {
-        "discovery": "bootstrap",
-        "bootstrapList": [
-          "/ip4/<RELAY-IP>/tcp/4001/p2p/<RELAY-PEER-ID>"
-        ],
-        "relayList": [
-          "/ip4/<RELAY-IP>/tcp/4001/p2p/<RELAY-PEER-ID>"
-        ]
+    "entries": {
+      "libp2p-mesh": {
+        "enabled": true,
+        "config": {
+          "discovery": "bootstrap",
+          "bootstrapList": [
+            "/ip4/<RELAY-IP>/tcp/4001/p2p/<RELAY-PEER-ID>"
+          ],
+          "relayList": [
+            "/ip4/<RELAY-IP>/tcp/4001/p2p/<RELAY-PEER-ID>"
+          ],
+          "enableNATTraversal": true,
+          "deliveryAckTimeoutMs": 15000
+        }
       }
     }
   }
@@ -222,13 +274,17 @@ Add `enableCircuitRelayServer: true` to your config and announce the public addr
 ```json
 {
   "plugins": {
-    "libp2p-mesh": {
-      "enabled": true,
-      "config": {
-        "discovery": "bootstrap",
-        "listenAddrs": ["/ip4/0.0.0.0/tcp/4001"],
-        "announceAddrs": ["/ip4/<PUBLIC-IP>/tcp/4001"],
-        "enableCircuitRelayServer": true
+    "entries": {
+      "libp2p-mesh": {
+        "enabled": true,
+        "config": {
+          "discovery": "bootstrap",
+          "listenAddrs": ["/ip4/0.0.0.0/tcp/4001"],
+          "announceAddrs": ["/ip4/<PUBLIC-IP>/tcp/4001"],
+          "enableNATTraversal": true,
+          "enableCircuitRelayServer": true,
+          "deliveryAckTimeoutMs": 15000
+        }
       }
     }
   }
@@ -308,75 +364,82 @@ $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:
+For inbound display, run the setup wizard on the receiving instance and add a target:
+
+```bash
+openclaw libp2p-mesh setup
+```
+
+The wizard edits `plugins.entries["libp2p-mesh"].config` and can add, edit, remove, or disable inbound delivery targets. You do not need to manually edit `openclaw.json`.
+
+Example result for a single Feishu target:
 
 ```json
 {
   "plugins": {
-    "libp2p-mesh": {
-      "enabled": true,
-      "config": {
-        "discovery": "mdns",
-        "inboundChannel": "feishu",
-        "inboundTarget": "user:ou_xxx",
-        "deliveryAckTimeoutMs": 15000
+    "entries": {
+      "libp2p-mesh": {
+        "enabled": true,
+        "config": {
+          "discovery": "mdns",
+          "inboundTargets": [
+            {
+              "id": "feishu-main",
+              "channel": "feishu",
+              "target": "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.
-
 ### Multi-channel inbound delivery
 
-To display the same inbound P2P message in multiple local OpenClaw channel targets, configure `inboundTargets` on the receiving instance:
+The sender still calls `p2p_send_instance_message({ "instanceId": "...", "message": "..." })`.
+The receiver chooses where inbound P2P messages appear:
 
 ```json
 {
   "plugins": {
-    "libp2p-mesh": {
-      "enabled": true,
-      "config": {
-        "discovery": "mdns",
-        "inboundTargets": [
-          {
-            "id": "feishu-user",
-            "channel": "feishu",
-            "target": "user:ou_xxx"
-          },
-          {
-            "id": "telegram-chat",
-            "channel": "telegram",
-            "target": "chat:123456"
-          }
-        ],
-        "deliveryAckTimeoutMs": 15000
+    "entries": {
+      "libp2p-mesh": {
+        "enabled": true,
+        "config": {
+          "discovery": "mdns",
+          "inboundTargets": [
+            {
+              "id": "feishu-main",
+              "channel": "feishu",
+              "target": "user:ou_xxx"
+            },
+            {
+              "id": "telegram-main",
+              "channel": "telegram",
+              "target": "chat:123456"
+            }
+          ],
+          "deliveryAckTimeoutMs": 15000
+        }
       }
     }
-  },
-  "channels": {
-    "libp2p-mesh": { "enabled": true }
   }
 }
 ```
 
-The sender still calls only:
+If `inboundTargets` is present, it is used instead of `inboundChannel`/`inboundTarget`.
+The sender receives per-target delivery status in the tool result.
+
+The OpenClaw agent should prefer:
 
 ```text
 p2p_send_instance_message({ "instanceId": "<target-instance-id>", "message": "今晚出来吃饭" })
 ```
 
-The sender does not choose the receiver channel. The receiving instance owns that routing decision through `inboundTargets`, and the message appears in each configured `channel`/`target`. Each target can include an `id`, which is shown in the sender-side tool result alongside each target's success or failure status.
+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()`.
 

package/api.ts

@@ -3,11 +3,9 @@ export { createInstancePeerStore } from "./src/instance-peer-store.js";
 export { createInstanceRouter } from "./src/instance-router.js";
 export type {
   DeliveryAckPayload,
-  DeliveryTargetResult,
   InboundDeliveryAdapter,
   InboundDeliveryRequest,
   InboundDeliveryResult,
-  InboundTargetConfig,
   InstanceAnnouncePayload,
   InstanceIdentity,
   InstancePeerRecord,

package/dist/api.d.ts

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

package/dist/index.d.ts

@@ -1,9 +1,3 @@
-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;
+import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/core";
+declare const plugin: OpenClawPluginDefinition;
+export default plugin;

package/dist/index.js

@@ -1,6 +1,5 @@
 import { definePluginEntry } from "openclaw/plugin-sdk/core";
 import { registerLibp2pMesh } from "./src/plugin.js";
-import { registerLibp2pMeshCli } from "./src/cli.js";
 function createLibp2pMeshConfigSchema() {
     return {
         safeParse(value) {
@@ -160,25 +159,11 @@ function createLibp2pMeshConfigSchema() {
         },
     };
 }
-export default definePluginEntry({
+const plugin = definePluginEntry({
     id: "libp2p-mesh",
     name: "libp2p Mesh Network",
     description: "P2P network for cross-instance agent communication via libp2p.",
     configSchema: createLibp2pMeshConfigSchema(),
-    register: (api) => {
-        if (api.registrationMode === "cli-metadata" ||
-            api.registrationMode === "discovery" ||
-            api.registrationMode === "full") {
-            api.registerCli(registerLibp2pMeshCli, {
-                commands: ["libp2p-mesh"],
-            });
-            if (api.registrationMode === "cli-metadata") {
-                return;
-            }
-        }
-        if (api.registrationMode !== "full") {
-            return;
-        }
-        registerLibp2pMesh(api);
-    },
+    register: registerLibp2pMesh,
 });
+export default plugin;

package/dist/src/agent-tools.js

@@ -1,19 +1,16 @@
 function targetLabel(result) {
-    const id = result.id?.trim();
-    const location = `${result.channel} / ${result.target}`;
-    return id ? `${id} (${location})` : location;
+    const name = result.id ?? `${result.channel}:${result.target}`;
+    return `${name} (${result.channel} / ${result.target})`;
 }
 function formatDeliveryResults(instanceId, delivered, results) {
-    const header = delivered
-        ? `发往 ${instanceId} 的消息投递结果：`
-        : `发往 ${instanceId} 的消息投递失败：`;
+    const heading = delivered
+        ? `发往 ${instanceId} 的消息投递结果`
+        : `发往 ${instanceId} 的消息投递失败`;
     const lines = results.map((result) => {
-        if (result.ok) {
-            return `- ${targetLabel(result)}：已送达`;
-        }
-        return `- ${targetLabel(result)}：失败：${result.error ?? "unknown error"}`;
+        const status = result.ok ? "已送达" : `失败：${result.error ?? "unknown error"}`;
+        return `${targetLabel(result)}：${status}`;
     });
-    return [header, ...lines].join("\n");
+    return [heading, ...lines].join("\n");
 }
 export function buildP2PTools(mesh, router) {
     return [