libp2p-mesh 2026.5.16 → 2026.5.18

package/README.md

@@ -42,7 +42,9 @@ openclaw plugins registry --refresh
 
 The published npm package includes compiled JavaScript under `dist/`, so OpenClaw and acpx can load it directly.
 
-Then add to your `~/.openclaw/openclaw.json`:
+After installing the plugin, you must:
+
+1. **Enable the plugin** in `~/.openclaw/openclaw.json`:
 
 ```json
 {
@@ -62,6 +64,78 @@ Then add to your `~/.openclaw/openclaw.json`:
 }
 ```
 
+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`:

package/dist/src/agent-tools.d.ts

@@ -14,6 +14,7 @@ export declare function buildP2PTools(mesh: MeshNetwork): ({
                 type: "string";
                 description: string;
             };
+            instanceId?: undefined;
             topic?: undefined;
         };
         required: string[];
@@ -44,6 +45,78 @@ export declare function buildP2PTools(mesh: MeshNetwork): ({
         };
         isError: boolean;
     }>;
+} | {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: {
+            instanceId: {
+                type: "string";
+                description: string;
+            };
+            message: {
+                type: "string";
+                description: string;
+            };
+            peerId?: undefined;
+            topic?: undefined;
+        };
+        required: string[];
+    };
+    execute(_toolCallId: string, params: {
+        instanceId: string;
+        message: string;
+    }, _ctx: any): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {
+            sent: boolean;
+            error: string;
+            instanceId?: undefined;
+            peerId?: undefined;
+        };
+        isError: boolean;
+    } | {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {
+            sent: boolean;
+            instanceId: string;
+            error?: undefined;
+            peerId?: undefined;
+        };
+        isError: boolean;
+    } | {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {
+            sent: boolean;
+            instanceId: string;
+            peerId: any;
+            error?: undefined;
+        };
+        isError?: undefined;
+    } | {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {
+            sent: boolean;
+            instanceId: string;
+            error: string;
+            peerId?: undefined;
+        };
+        isError: boolean;
+    }>;
 } | {
     name: string;
     label: string;
@@ -60,6 +133,7 @@ export declare function buildP2PTools(mesh: MeshNetwork): ({
                 description: string;
             };
             peerId?: undefined;
+            instanceId?: undefined;
         };
         required: string[];
     };
@@ -98,19 +172,21 @@ export declare function buildP2PTools(mesh: MeshNetwork): ({
         properties: {
             peerId?: undefined;
             message?: undefined;
+            instanceId?: undefined;
             topic?: undefined;
         };
         required?: undefined;
     };
-    execute(_toolCallId: string): Promise<{
+    execute(_toolCallId: string, _params: any, ctx: any): Promise<{
         content: {
             type: "text";
             text: string;
         }[];
         details: {
-            localPeerId: string;
-            connectedPeers: string[];
-            count: number;
+            peers: {
+                instanceId: any;
+                channel: any;
+            }[];
             error?: undefined;
         };
         isError?: undefined;
@@ -121,9 +197,7 @@ export declare function buildP2PTools(mesh: MeshNetwork): ({
         }[];
         details: {
             error: string;
-            localPeerId?: undefined;
-            connectedPeers?: undefined;
-            count?: undefined;
+            peers?: undefined;
         };
         isError: boolean;
     }>;
@@ -136,6 +210,7 @@ export declare function buildP2PTools(mesh: MeshNetwork): ({
         properties: {
             peerId?: undefined;
             message?: undefined;
+            instanceId?: undefined;
             topic?: undefined;
         };
         required?: undefined;
@@ -183,6 +258,7 @@ export declare function buildP2PTools(mesh: MeshNetwork): ({
         properties: {
             peerId?: undefined;
             message?: undefined;
+            instanceId?: undefined;
             topic?: undefined;
         };
         required?: undefined;
@@ -214,4 +290,31 @@ export declare function buildP2PTools(mesh: MeshNetwork): ({
         };
         isError: boolean;
     }>;
+} | {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: {
+            peerId?: undefined;
+            message?: undefined;
+            instanceId?: undefined;
+            topic?: undefined;
+        };
+        required?: undefined;
+    };
+    execute(_toolCallId: string, _params: {}, _ctx: any): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {
+            knownIdentities: ({
+                instanceId: any;
+                agentId: any;
+                channel: any;
+            } | null)[];
+        };
+    }>;
 })[];

package/dist/src/agent-tools.js

@@ -3,7 +3,7 @@ export function buildP2PTools(mesh) {
         {
             name: "p2p_send_message",
             label: "P2P Send Message",
-            description: "Send a direct message to another agent via the P2P mesh network.",
+            description: "Send a direct message to another agent via the P2P mesh network by Peer ID.",
             parameters: {
                 type: "object",
                 properties: {
@@ -40,6 +40,72 @@ export function buildP2PTools(mesh) {
                 }
             },
         },
+        {
+            name: "p2p_send_to_instance",
+            label: "P2P Send to Instance",
+            description: "Send a direct message to a peer by its human-readable Instance ID (e.g. alice-mac).",
+            parameters: {
+                type: "object",
+                properties: {
+                    instanceId: {
+                        type: "string",
+                        description: "Target Instance ID (e.g. alice-mac@AQIDBAU.7a3f9e2b)",
+                    },
+                    message: {
+                        type: "string",
+                        description: "Message content to send",
+                    },
+                },
+                required: ["instanceId", "message"],
+            },
+            async execute(_toolCallId, params, _ctx) {
+                const peerIdentityMap = _ctx?.peerIdentityMap;
+                if (!peerIdentityMap) {
+                    return {
+                        content: [{ type: "text", text: "Internal error: peer identity map not available." }],
+                        details: { sent: false, error: "peerIdentityMap missing" },
+                        isError: true,
+                    };
+                }
+                const lookup = peerIdentityMap.resolveByInstanceId(params.instanceId);
+                if (!lookup) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Unknown Instance ID: "${params.instanceId}". Use p2p_list_peers to see available users.`,
+                            },
+                        ],
+                        details: { sent: false, instanceId: params.instanceId },
+                        isError: true,
+                    };
+                }
+                try {
+                    await mesh.sendToPeer(lookup.peerId, params.message);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Message sent to ${params.instanceId}`,
+                            },
+                        ],
+                        details: { sent: true, instanceId: params.instanceId, peerId: lookup.peerId },
+                    };
+                }
+                catch (err) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Failed to send message to ${params.instanceId}: ${String(err)}`,
+                            },
+                        ],
+                        details: { sent: false, instanceId: params.instanceId, error: String(err) },
+                        isError: true,
+                    };
+                }
+            },
+        },
         {
             name: "p2p_broadcast",
             label: "P2P Broadcast",
@@ -83,24 +149,42 @@ export function buildP2PTools(mesh) {
         {
             name: "p2p_list_peers",
             label: "P2P List Peers",
-            description: "List currently connected peers in the P2P mesh network.",
+            description: "List currently connected peers with their Instance IDs and channels.",
             parameters: {
                 type: "object",
                 properties: {},
             },
-            async execute(_toolCallId) {
+            async execute(_toolCallId, _params, ctx) {
                 try {
+                    const peerIdentityMap = ctx?.peerIdentityMap;
                     const peers = mesh.getConnectedPeers();
-                    const text = peers.length === 0
-                        ? "No peers currently connected."
-                        : `Connected peers (${peers.length}): ${peers.join(", ")}`;
+                    if (peers.length === 0) {
+                        return {
+                            content: [{ type: "text", text: "No peers currently connected." }],
+                            details: { peers: [] },
+                        };
+                    }
+                    const userList = peers
+                        .map((p) => {
+                        const identity = peerIdentityMap?.resolve(p);
+                        if (identity?.instanceId) {
+                            const ch = identity.channel ? ` (${identity.channel})` : "";
+                            return `  - ${identity.instanceId}${ch}`;
+                        }
+                        return `  - ${p.slice(0, 12)}... (identity unknown)`;
+                    })
+                        .join("\n");
+                    const text = `在线用户 (${peers.length})：\n${userList}`;
+                    const safePeers = peers.map((p) => {
+                        const identity = peerIdentityMap?.resolve(p);
+                        return {
+                            instanceId: identity?.instanceId || p.slice(0, 12) + "...",
+                            channel: identity?.channel || "unknown",
+                        };
+                    });
                     return {
                         content: [{ type: "text", text }],
-                        details: {
-                            localPeerId: mesh.getLocalPeerId(),
-                            connectedPeers: peers,
-                            count: peers.length,
-                        },
+                        details: { peers: safePeers },
                     };
                 }
                 catch (err) {
@@ -191,5 +275,33 @@ export function buildP2PTools(mesh) {
                 }
             },
         },
+        {
+            name: "p2p_relay_status",
+            label: "P2P Relay Status",
+            description: "Get current P2P mesh connection status, known peers, and identity mapping.",
+            parameters: { type: "object", properties: {} },
+            async execute(_toolCallId, _params, _ctx) {
+                const peerIdentityMap = this.peerIdentityMap;
+                const localPeerId = mesh.getLocalPeerId();
+                const connectedPeers = mesh.getConnectedPeers();
+                const knownIdentities = connectedPeers
+                    .map((p) => {
+                    const identity = peerIdentityMap?.resolve(p);
+                    if (!identity)
+                        return null;
+                    return {
+                        instanceId: identity.instanceId || p.slice(0, 12) + "...",
+                        agentId: identity.agentId,
+                        channel: identity.channel,
+                    };
+                })
+                    .filter(Boolean);
+                const text = `P2P Mesh Status:\nLocal Peer ID: ${localPeerId}\nConnected Peers: ${connectedPeers.length}\nKnown Identities: ${knownIdentities.length}`;
+                return {
+                    content: [{ type: "text", text }],
+                    details: { knownIdentities },
+                };
+            },
+        },
     ];
 }

package/dist/src/identity-exchange.d.ts

@@ -0,0 +1,13 @@
+import type { P2PMessage } from "./types.js";
+import type { PeerIdentityMap } from "./peer-identity.ts";
+export interface IdentityExchangeDeps {
+    peerIdentityMap: PeerIdentityMap;
+    localPeerId: string;
+    localAgentId: string;
+    localChannel: string;
+    localAccountId: string;
+    localInstanceId?: string;
+    send: (peerId: string, message: P2PMessage) => Promise<void>;
+}
+export declare function buildIdentityMessage(peerId: string, agentId: string, channel: string, accountId: string, instanceId?: string): P2PMessage;
+export declare function handleIdentityMessage(msg: P2PMessage, deps: IdentityExchangeDeps): Promise<void>;

package/dist/src/identity-exchange.js

@@ -0,0 +1,36 @@
+export function buildIdentityMessage(peerId, agentId, channel, accountId, instanceId) {
+    return {
+        id: crypto.randomUUID(),
+        type: "identity",
+        from: peerId,
+        payload: JSON.stringify({ agentId, channel, accountId, instanceId }),
+        timestamp: Date.now(),
+    };
+}
+export async function handleIdentityMessage(msg, deps) {
+    // Parse remote identity payload
+    let parsed = {};
+    try {
+        parsed = JSON.parse(msg.payload);
+    }
+    catch {
+        // Malformed payload — skip silently
+        return;
+    }
+    const { agentId, channel, accountId, instanceId } = parsed;
+    // Only register if all required fields are present
+    if (agentId && channel && accountId) {
+        const { buildAgentSessionKey } = await import("openclaw/plugin-sdk/core");
+        const sessionKey = buildAgentSessionKey({ agentId, channel, accountId });
+        deps.peerIdentityMap.register(msg.from, {
+            agentId,
+            channel,
+            accountId,
+            sessionKey,
+            instanceId,
+        });
+    }
+    // Send local identity back to the remote peer
+    const localIdentity = buildIdentityMessage(deps.localPeerId, deps.localAgentId, deps.localChannel, deps.localAccountId, deps.localInstanceId);
+    await deps.send(msg.from, localIdentity);
+}

package/dist/src/inbound.d.ts

@@ -1,10 +1,17 @@
 import type { P2PMessage } from "./types.js";
-export type InboundHandlerDeps = {
+import type { PeerIdentityMap } from "./peer-identity.ts";
+import type { PluginNextTurnInjection } from "openclaw/plugin-sdk/core";
+export interface InboundHandlerDeps {
+    peerIdentityMap?: PeerIdentityMap;
+    enqueueNextTurnInjection?: (injection: PluginNextTurnInjection) => Promise<{
+        enqueued: boolean;
+        id: string;
+    }>;
     logger?: {
         info?: (msg: string) => void;
         debug?: (msg: string) => void;
         warn?: (msg: string) => void;
         error?: (msg: string) => void;
     };
-};
-export declare function handleP2PInbound(msg: P2PMessage, deps: InboundHandlerDeps): void;
+}
+export declare function handleP2PInbound(msg: P2PMessage, deps?: InboundHandlerDeps): void;

package/dist/src/inbound.js

@@ -1,6 +1,7 @@
 import { verifyInstanceSignature } from "./instance-id.js";
+import { buildAgentSessionKey } from "openclaw/plugin-sdk/core";
 export function handleP2PInbound(msg, deps) {
-    const { logger } = deps;
+    const logger = deps?.logger;
     const instanceTag = msg.instanceId ? ` [instance: ${msg.instanceId}]` : "";
     const signedTag = msg.signature ? " [signed]" : "";
     // Verify signature if present
@@ -15,7 +16,14 @@ export function handleP2PInbound(msg, deps) {
             timestamp: msg.timestamp,
             instanceId: msg.instanceId,
         });
-        const valid = verifyInstanceSignature({ id: msg.instanceId, name: "", pubkey: msg.pubkey, binding: "", bindingComponents: { username: "", hostname: "", platform: "" }, createdAt: 0 }, signedPayload, msg.signature);
+        const valid = verifyInstanceSignature({
+            id: msg.instanceId,
+            name: "",
+            pubkey: msg.pubkey,
+            binding: "",
+            bindingComponents: { username: "", hostname: "", platform: "" },
+            createdAt: 0,
+        }, signedPayload, msg.signature);
         if (valid) {
             logger?.info?.(`[libp2p-mesh] Verified signature from instance ${msg.instanceId}`);
         }
@@ -26,6 +34,67 @@ export function handleP2PInbound(msg, deps) {
     else if (msg.signature) {
         logger?.warn?.(`[libp2p-mesh] Message has signature but no pubkey; cannot verify`);
     }
+    // Relay handling when deps are provided with required fields
+    if (deps?.peerIdentityMap && deps?.enqueueNextTurnInjection) {
+        if (msg.type === "identity") {
+            // Parse remote identity payload and register synchronously
+            let parsed = {};
+            try {
+                parsed = JSON.parse(msg.payload);
+            }
+            catch {
+                // Malformed payload — skip silently
+                return;
+            }
+            const { agentId, channel, accountId, instanceId } = parsed;
+            if (agentId && channel && accountId) {
+                const sessionKey = buildAgentSessionKey({ agentId, channel, accountId });
+                deps.peerIdentityMap.register(msg.from, {
+                    agentId,
+                    channel,
+                    accountId,
+                    sessionKey,
+                    instanceId,
+                });
+            }
+        }
+        else if (msg.type === "direct") {
+            if (!msg.to) {
+                logger?.warn?.("[libp2p-mesh] Direct message missing 'to' field");
+            }
+            else {
+                const receiver = deps.peerIdentityMap.resolve(msg.to);
+                if (!receiver) {
+                    logger?.warn?.(`[libp2p-mesh] Unknown recipient peer: ${msg.to}`);
+                }
+                else {
+                    const sessionKey = buildAgentSessionKey({
+                        agentId: receiver.agentId,
+                        channel: receiver.channel,
+                        accountId: receiver.accountId,
+                    });
+                    const text = `【来自P2P网络的消息】\n来源：${msg.from}\n内容：${msg.payload}\n\n` +
+                        `请你通过你当前的 channel 将此消息转发给你所服务的用户。转发完成后，请务必调用 p2p_send_message 工具向 ${msg.from} 回复送达确认。`;
+                    deps.enqueueNextTurnInjection({ sessionKey, text, placement: "prepend_context" });
+                }
+            }
+        }
+        else if (msg.type === "broadcast") {
+            const topic = msg.topic || "(none)";
+            const text = `【来自P2P网络的广播消息】\n话题：${topic}\n来源：${msg.from}\n内容：${msg.payload}\n\n` +
+                `请你通过你当前的 channel 将此广播消息转发给你所服务的用户。`;
+            // Inject broadcast into each known peer's session
+            for (const [, identity] of deps.peerIdentityMap.entries()) {
+                const sessionKey = buildAgentSessionKey({
+                    agentId: identity.agentId,
+                    channel: identity.channel,
+                    accountId: identity.accountId,
+                });
+                deps.enqueueNextTurnInjection({ sessionKey, text, placement: "prepend_context" });
+            }
+        }
+    }
+    // Original logging (unchanged)
     if (msg.type === "broadcast") {
         logger?.info?.(`[libp2p-mesh] Broadcast from ${msg.from}${instanceTag}${signedTag} on topic ${msg.topic ?? "(none)"}: ${msg.payload}`);
     }

package/dist/src/mesh.js

@@ -214,11 +214,11 @@ export function createMeshNetwork(options) {
         });
         state.node.addEventListener("peer:connect", (evt) => {
             const peerIdStr = evt.detail.toString();
-            logger?.debug?.(`[libp2p-mesh] Peer connected: ${peerIdStr}`);
+            logger?.info?.(`[libp2p-mesh] Peer connected: ${peerIdStr}`);
         });
         state.node.addEventListener("peer:disconnect", (evt) => {
             const peerIdStr = evt.detail.toString();
-            logger?.debug?.(`[libp2p-mesh] Peer disconnected: ${peerIdStr}`);
+            logger?.info?.(`[libp2p-mesh] Peer disconnected: ${peerIdStr}`);
         });
         await state.node.handle(PROTOCOL, async ({ stream, connection }) => {
             try {

package/dist/src/peer-identity.d.ts

@@ -0,0 +1,23 @@
+export interface PeerIdentity {
+    agentId: string;
+    channel: string;
+    accountId: string;
+    sessionKey: string;
+    /** Human-readable Instance ID (e.g. "alice-mac@AQIDBAU.7a3f9e2b") */
+    instanceId?: string;
+}
+export interface PeerIdentityMap {
+    register(peerId: string, identity: PeerIdentity): void;
+    resolve(peerId: string): PeerIdentity | undefined;
+    resolveSessionKey(peerId: string): string | undefined;
+    resolveByInstanceId(instanceId: string): {
+        peerId: string;
+        identity: PeerIdentity;
+    } | undefined;
+    unregister(peerId: string): void;
+    setLocalIdentity(peerId: string, identity: PeerIdentity): void;
+    getLocalIdentity(): PeerIdentity | undefined;
+    hasIdentity(peerId: string): boolean;
+    entries(): IterableIterator<[string, PeerIdentity]>;
+}
+export declare function createPeerIdentityMap(): PeerIdentityMap;

package/dist/src/peer-identity.js

@@ -0,0 +1,47 @@
+export function createPeerIdentityMap() {
+    const peers = new Map();
+    const byInstanceId = new Map();
+    let localPeerId;
+    let localIdentity;
+    return {
+        register(peerId, identity) {
+            peers.set(peerId, identity);
+            if (identity.instanceId) {
+                byInstanceId.set(identity.instanceId, { peerId, identity });
+            }
+        },
+        resolve(peerId) {
+            return peers.get(peerId);
+        },
+        resolveSessionKey(peerId) {
+            return peers.get(peerId)?.sessionKey;
+        },
+        resolveByInstanceId(instanceId) {
+            return byInstanceId.get(instanceId);
+        },
+        unregister(peerId) {
+            const identity = peers.get(peerId);
+            if (identity?.instanceId) {
+                byInstanceId.delete(identity.instanceId);
+            }
+            peers.delete(peerId);
+        },
+        setLocalIdentity(peerId, identity) {
+            localPeerId = peerId;
+            localIdentity = identity;
+            peers.set(peerId, identity);
+            if (identity.instanceId) {
+                byInstanceId.set(identity.instanceId, { peerId, identity });
+            }
+        },
+        getLocalIdentity() {
+            return localIdentity;
+        },
+        hasIdentity(peerId) {
+            return peers.has(peerId);
+        },
+        entries() {
+            return peers.entries();
+        },
+    };
+}