libp2p-mesh 2026.5.17 → 2026.5.19

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;
@@ -223,6 +299,7 @@ export declare function buildP2PTools(mesh: MeshNetwork): ({
         properties: {
             peerId?: undefined;
             message?: undefined;
+            instanceId?: undefined;
             topic?: undefined;
         };
         required?: undefined;
@@ -233,12 +310,11 @@ export declare function buildP2PTools(mesh: MeshNetwork): ({
             text: string;
         }[];
         details: {
-            localPeerId: string;
-            connectedPeers: string[];
-            knownIdentities: {
-                peerId: string;
-                identity: any;
-            }[];
+            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) {
@@ -201,12 +285,21 @@ export function buildP2PTools(mesh) {
                 const localPeerId = mesh.getLocalPeerId();
                 const connectedPeers = mesh.getConnectedPeers();
                 const knownIdentities = connectedPeers
-                    .map((p) => ({ peerId: p, identity: peerIdentityMap?.resolve(p) }))
-                    .filter((entry) => entry.identity !== undefined);
+                    .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: { localPeerId, connectedPeers, knownIdentities },
+                    details: { knownIdentities },
                 };
             },
         },

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

@@ -6,7 +6,8 @@ export interface IdentityExchangeDeps {
     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): P2PMessage;
+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

@@ -1,9 +1,9 @@
-export function buildIdentityMessage(peerId, agentId, channel, accountId) {
+export function buildIdentityMessage(peerId, agentId, channel, accountId, instanceId) {
     return {
         id: crypto.randomUUID(),
         type: "identity",
         from: peerId,
-        payload: JSON.stringify({ agentId, channel, accountId }),
+        payload: JSON.stringify({ agentId, channel, accountId, instanceId }),
         timestamp: Date.now(),
     };
 }
@@ -17,7 +17,7 @@ export async function handleIdentityMessage(msg, deps) {
         // Malformed payload — skip silently
         return;
     }
-    const { agentId, channel, accountId } = parsed;
+    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");
@@ -27,9 +27,10 @@ export async function handleIdentityMessage(msg, deps) {
             channel,
             accountId,
             sessionKey,
+            instanceId,
         });
     }
     // Send local identity back to the remote peer
-    const localIdentity = buildIdentityMessage(deps.localPeerId, deps.localAgentId, deps.localChannel, deps.localAccountId);
+    const localIdentity = buildIdentityMessage(deps.localPeerId, deps.localAgentId, deps.localChannel, deps.localAccountId, deps.localInstanceId);
     await deps.send(msg.from, localIdentity);
 }

package/dist/src/inbound.js

@@ -46,7 +46,7 @@ export function handleP2PInbound(msg, deps) {
                 // Malformed payload — skip silently
                 return;
             }
-            const { agentId, channel, accountId } = parsed;
+            const { agentId, channel, accountId, instanceId } = parsed;
             if (agentId && channel && accountId) {
                 const sessionKey = buildAgentSessionKey({ agentId, channel, accountId });
                 deps.peerIdentityMap.register(msg.from, {
@@ -54,6 +54,7 @@ export function handleP2PInbound(msg, deps) {
                     channel,
                     accountId,
                     sessionKey,
+                    instanceId,
                 });
             }
         }

package/dist/src/mesh.js

@@ -77,6 +77,8 @@ export function createMeshNetwork(options) {
     const seenMessages = new Set();
     const messageHandlers = new Set();
     const topicHandlers = new Map();
+    const peerConnectHandlers = new Set();
+    const peerDisconnectHandlers = new Set();
     function getDHTService() {
         return state.node?.services?.dht;
     }
@@ -215,10 +217,22 @@ export function createMeshNetwork(options) {
         state.node.addEventListener("peer:connect", (evt) => {
             const peerIdStr = evt.detail.toString();
             logger?.info?.(`[libp2p-mesh] Peer connected: ${peerIdStr}`);
+            for (const handler of peerConnectHandlers) {
+                try {
+                    handler(peerIdStr);
+                }
+                catch { }
+            }
         });
         state.node.addEventListener("peer:disconnect", (evt) => {
             const peerIdStr = evt.detail.toString();
             logger?.info?.(`[libp2p-mesh] Peer disconnected: ${peerIdStr}`);
+            for (const handler of peerDisconnectHandlers) {
+                try {
+                    handler(peerIdStr);
+                }
+                catch { }
+            }
         });
         await state.node.handle(PROTOCOL, async ({ stream, connection }) => {
             try {
@@ -580,6 +594,14 @@ export function createMeshNetwork(options) {
         stop,
         sendToPeer,
         onMessage,
+        onPeerConnect(handler) {
+            peerConnectHandlers.add(handler);
+            return () => { peerConnectHandlers.delete(handler); };
+        },
+        onPeerDisconnect(handler) {
+            peerDisconnectHandlers.add(handler);
+            return () => { peerDisconnectHandlers.delete(handler); };
+        },
         publishToTopic,
         subscribeToTopic,
         getLocalPeerId,

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

@@ -3,11 +3,17 @@ export interface PeerIdentity {
     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;

package/dist/src/peer-identity.js

@@ -1,10 +1,14 @@
 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);
@@ -12,13 +16,23 @@ export function createPeerIdentityMap() {
         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;

package/dist/src/plugin.js

@@ -24,12 +24,15 @@ export function registerLibp2pMesh(api) {
         id: "libp2p-mesh",
         start: async () => {
             await mesh.start();
-            // Register local identity so remote peers can route messages back to us
+            // Gather local relay identity info
             const config = api.pluginConfig;
             const relayChannel = config?.relayChannel;
             const relayAccountId = config?.relayAccountId;
+            const instanceIdentity = mesh.getInstanceIdentity();
+            const localInstanceId = instanceIdentity?.id;
+            const localPeerId = mesh.getLocalPeerId();
+            // Register local identity so remote peers can route messages back to us
             if (relayChannel && relayAccountId) {
-                const localPeerId = mesh.getLocalPeerId();
                 const { buildAgentSessionKey } = await import("openclaw/plugin-sdk/core");
                 const sessionKey = buildAgentSessionKey({
                     agentId: api.name,
@@ -41,12 +44,12 @@ export function registerLibp2pMesh(api) {
                     channel: relayChannel,
                     accountId: relayAccountId,
                     sessionKey,
+                    instanceId: localInstanceId,
                 });
-                api.logger.info?.(`[libp2p-mesh] Local identity registered: agent=${api.name}, channel=${relayChannel}, account=${relayAccountId}`);
+                api.logger.info?.(`[libp2p-mesh] Local identity registered: agent=${api.name}, channel=${relayChannel}, account=${relayAccountId}, instanceId=${localInstanceId}`);
                 // Announce identity to all currently-connected peers
-                const identityMsg = buildIdentityMessage(localPeerId, api.name, relayChannel, relayAccountId);
-                const connectedPeers = mesh.getConnectedPeers();
-                for (const peerId of connectedPeers) {
+                const identityMsg = buildIdentityMessage(localPeerId, api.name, relayChannel, relayAccountId, localInstanceId);
+                for (const peerId of mesh.getConnectedPeers()) {
                     try {
                         await mesh.sendToPeer(peerId, JSON.stringify(identityMsg));
                     }
@@ -54,13 +57,24 @@ export function registerLibp2pMesh(api) {
                         // Best-effort; peer may be stale in the connection list
                     }
                 }
+                // When a new peer connects, send our identity to them
+                mesh.onPeerConnect((peerId) => {
+                    const msg = buildIdentityMessage(localPeerId, api.name, relayChannel, relayAccountId, localInstanceId);
+                    mesh.sendToPeer(peerId, JSON.stringify(msg)).catch(() => {
+                        // Best-effort
+                    });
+                });
+                // When a peer disconnects, clean up the identity map
+                mesh.onPeerDisconnect((peerId) => {
+                    peerIdentityMap.unregister(peerId);
+                });
             }
             // Wire up relay-aware message handler
             mesh.onMessage((msg) => {
                 handleP2PInbound(msg, buildInboundDeps());
             });
             const identity = mesh.getInstanceIdentity();
-            api.logger.info?.(`[libp2p-mesh] Service started. Peer ID: ${mesh.getLocalPeerId()}`);
+            api.logger.info?.(`[libp2p-mesh] Service started. Peer ID: ${localPeerId}`);
             if (identity) {
                 api.logger.info?.(`[libp2p-mesh] Instance Identity: ${identity.id}`);
             }

package/dist/src/types.d.ts

@@ -106,6 +106,8 @@ export interface MeshNetwork {
     stop(): Promise<void>;
     sendToPeer(peerId: string, message: string): Promise<void>;
     onMessage(handler: (msg: P2PMessage) => void): () => void;
+    onPeerConnect(handler: (peerId: string) => void): () => void;
+    onPeerDisconnect(handler: (peerId: string) => void): () => void;
     publishToTopic(topic: string, message: string): Promise<void>;
     subscribeToTopic(topic: string, handler: (msg: string) => void): Promise<void>;
     getLocalPeerId(): string;

package/openclaw.plugin.json

@@ -116,6 +116,7 @@
   "contracts": {
     "tools": [
       "p2p_send_message",
+      "p2p_send_to_instance",
       "p2p_broadcast",
       "p2p_list_peers",
       "p2p_get_instance_identity",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libp2p-mesh",
-  "version": "2026.5.17",
+  "version": "2026.5.19",
   "description": "OpenClaw libp2p P2P mesh network plugin for cross-instance agent communication",
   "type": "module",
   "main": "dist/index.js",

package/src/agent-tools.ts

@@ -1,11 +1,13 @@
 import type { MeshNetwork } from "./types.js";
+import type { PeerIdentity } from "./peer-identity.ts";
+import type { PeerIdentityMap } from "./peer-identity.ts";
 
 export function buildP2PTools(mesh: MeshNetwork) {
   return [
     {
       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" as const,
         properties: {
@@ -41,6 +43,71 @@ export function buildP2PTools(mesh: MeshNetwork) {
         }
       },
     },
+    {
+      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" as const,
+        properties: {
+          instanceId: {
+            type: "string" as const,
+            description: "Target Instance ID (e.g. alice-mac@AQIDBAU.7a3f9e2b)",
+          },
+          message: {
+            type: "string" as const,
+            description: "Message content to send",
+          },
+        },
+        required: ["instanceId", "message"],
+      },
+      async execute(_toolCallId: string, params: { instanceId: string; message: string }, _ctx: any) {
+        const peerIdentityMap = (_ctx as any)?.peerIdentityMap;
+        if (!peerIdentityMap) {
+          return {
+            content: [{ type: "text" as const, 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" as const,
+                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" as const,
+                text: `Message sent to ${params.instanceId}`,
+              },
+            ],
+            details: { sent: true, instanceId: params.instanceId, peerId: lookup.peerId },
+          };
+        } catch (err) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                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,25 +150,42 @@ export function buildP2PTools(mesh: MeshNetwork) {
     {
       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" as const,
         properties: {},
       },
-      async execute(_toolCallId: string) {
+      async execute(_toolCallId: string, _params: any, ctx: any) {
         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" as const, 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" as const, text }],
-            details: {
-              localPeerId: mesh.getLocalPeerId(),
-              connectedPeers: peers,
-              count: peers.length,
-            },
+            details: { peers: safePeers },
           };
         } catch (err) {
           return {
@@ -201,12 +285,20 @@ export function buildP2PTools(mesh: MeshNetwork) {
         const localPeerId = mesh.getLocalPeerId();
         const connectedPeers = mesh.getConnectedPeers();
         const knownIdentities = connectedPeers
-          .map((p) => ({ peerId: p, identity: peerIdentityMap?.resolve(p) }))
-          .filter((entry) => entry.identity !== undefined);
+          .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" as const, text }],
-          details: { localPeerId, connectedPeers, knownIdentities },
+          details: { knownIdentities },
         };
       },
     },

package/src/identity-exchange.ts

@@ -7,6 +7,7 @@ export interface IdentityExchangeDeps {
   localAgentId: string;
   localChannel: string;
   localAccountId: string;
+  localInstanceId?: string;
   send: (peerId: string, message: P2PMessage) => Promise<void>;
 }
 
@@ -15,12 +16,13 @@ export function buildIdentityMessage(
   agentId: string,
   channel: string,
   accountId: string,
+  instanceId?: string,
 ): P2PMessage {
   return {
     id: crypto.randomUUID(),
     type: "identity",
     from: peerId,
-    payload: JSON.stringify({ agentId, channel, accountId }),
+    payload: JSON.stringify({ agentId, channel, accountId, instanceId }),
     timestamp: Date.now(),
   };
 }
@@ -30,7 +32,7 @@ export async function handleIdentityMessage(
   deps: IdentityExchangeDeps,
 ): Promise<void> {
   // Parse remote identity payload
-  let parsed: { agentId?: string; channel?: string; accountId?: string } = {};
+  let parsed: { agentId?: string; channel?: string; accountId?: string; instanceId?: string } = {};
   try {
     parsed = JSON.parse(msg.payload);
   } catch {
@@ -38,7 +40,7 @@ export async function handleIdentityMessage(
     return;
   }
 
-  const { agentId, channel, accountId } = parsed;
+  const { agentId, channel, accountId, instanceId } = parsed;
 
   // Only register if all required fields are present
   if (agentId && channel && accountId) {
@@ -49,6 +51,7 @@ export async function handleIdentityMessage(
       channel,
       accountId,
       sessionKey,
+      instanceId,
     });
   }
 
@@ -58,6 +61,7 @@ export async function handleIdentityMessage(
     deps.localAgentId,
     deps.localChannel,
     deps.localAccountId,
+    deps.localInstanceId,
   );
   await deps.send(msg.from, localIdentity);
 }

package/src/inbound.ts

@@ -57,7 +57,7 @@ export function handleP2PInbound(msg: P2PMessage, deps?: InboundHandlerDeps): vo
   if (deps?.peerIdentityMap && deps?.enqueueNextTurnInjection) {
     if (msg.type === "identity") {
       // Parse remote identity payload and register synchronously
-      let parsed: { agentId?: string; channel?: string; accountId?: string } = {};
+      let parsed: { agentId?: string; channel?: string; accountId?: string; instanceId?: string } = {};
       try {
         parsed = JSON.parse(msg.payload);
       } catch {
@@ -65,7 +65,7 @@ export function handleP2PInbound(msg: P2PMessage, deps?: InboundHandlerDeps): vo
         return;
       }
 
-      const { agentId, channel, accountId } = parsed;
+      const { agentId, channel, accountId, instanceId } = parsed;
 
       if (agentId && channel && accountId) {
         const sessionKey = buildAgentSessionKey({ agentId, channel, accountId });
@@ -74,6 +74,7 @@ export function handleP2PInbound(msg: P2PMessage, deps?: InboundHandlerDeps): vo
           channel,
           accountId,
           sessionKey,
+          instanceId,
         });
       }
     } else if (msg.type === "direct") {

package/src/mesh.ts

@@ -94,6 +94,8 @@ export function createMeshNetwork(options: {
   const seenMessages = new Set<string>();
   const messageHandlers = new Set<(msg: P2PMessage) => void>();
   const topicHandlers = new Map<string, Set<(msg: string) => void>>();
+  const peerConnectHandlers = new Set<(peerId: string) => void>();
+  const peerDisconnectHandlers = new Set<(peerId: string) => void>();
 
   function getDHTService(): ReturnType<typeof kadDHT> extends (components: infer C) => infer R ? R : never | undefined {
     return (state.node as any)?.services?.dht;
@@ -258,11 +260,17 @@ export function createMeshNetwork(options: {
     state.node.addEventListener("peer:connect", (evt) => {
       const peerIdStr = evt.detail.toString();
       logger?.info?.(`[libp2p-mesh] Peer connected: ${peerIdStr}`);
+      for (const handler of peerConnectHandlers) {
+        try { handler(peerIdStr); } catch {}
+      }
     });
 
     state.node.addEventListener("peer:disconnect", (evt) => {
       const peerIdStr = evt.detail.toString();
       logger?.info?.(`[libp2p-mesh] Peer disconnected: ${peerIdStr}`);
+      for (const handler of peerDisconnectHandlers) {
+        try { handler(peerIdStr); } catch {}
+      }
     });
 
     await state.node.handle(
@@ -667,6 +675,14 @@ export function createMeshNetwork(options: {
     stop,
     sendToPeer,
     onMessage,
+    onPeerConnect(handler: (peerId: string) => void): () => void {
+      peerConnectHandlers.add(handler);
+      return () => { peerConnectHandlers.delete(handler); };
+    },
+    onPeerDisconnect(handler: (peerId: string) => void): () => void {
+      peerDisconnectHandlers.add(handler);
+      return () => { peerDisconnectHandlers.delete(handler); };
+    },
     publishToTopic,
     subscribeToTopic,
     getLocalPeerId,

package/src/peer-identity.ts

@@ -3,12 +3,15 @@ export interface PeerIdentity {
   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;
@@ -18,12 +21,16 @@ export interface PeerIdentityMap {
 
 export function createPeerIdentityMap(): PeerIdentityMap {
   const peers = new Map<string, PeerIdentity>();
+  const byInstanceId = new Map<string, { peerId: string; identity: PeerIdentity }>();
   let localPeerId: string | undefined;
   let localIdentity: PeerIdentity | undefined;
 
   return {
     register(peerId: string, identity: PeerIdentity): void {
       peers.set(peerId, identity);
+      if (identity.instanceId) {
+        byInstanceId.set(identity.instanceId, { peerId, identity });
+      }
     },
 
     resolve(peerId: string): PeerIdentity | undefined {
@@ -34,7 +41,15 @@ export function createPeerIdentityMap(): PeerIdentityMap {
       return peers.get(peerId)?.sessionKey;
     },
 
+    resolveByInstanceId(instanceId: string): { peerId: string; identity: PeerIdentity } | undefined {
+      return byInstanceId.get(instanceId);
+    },
+
     unregister(peerId: string): void {
+      const identity = peers.get(peerId);
+      if (identity?.instanceId) {
+        byInstanceId.delete(identity.instanceId);
+      }
       peers.delete(peerId);
     },
 
@@ -42,6 +57,9 @@ export function createPeerIdentityMap(): PeerIdentityMap {
       localPeerId = peerId;
       localIdentity = identity;
       peers.set(peerId, identity);
+      if (identity.instanceId) {
+        byInstanceId.set(identity.instanceId, { peerId, identity });
+      }
     },
 
     getLocalIdentity(): PeerIdentity | undefined {

package/src/plugin.ts

@@ -33,12 +33,16 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
     start: async () => {
       await mesh.start();
 
-      // Register local identity so remote peers can route messages back to us
+      // Gather local relay identity info
       const config = api.pluginConfig as MeshConfig | undefined;
       const relayChannel = config?.relayChannel;
       const relayAccountId = config?.relayAccountId;
+      const instanceIdentity = mesh.getInstanceIdentity();
+      const localInstanceId = instanceIdentity?.id;
+      const localPeerId = mesh.getLocalPeerId();
+
+      // Register local identity so remote peers can route messages back to us
       if (relayChannel && relayAccountId) {
-        const localPeerId = mesh.getLocalPeerId();
         const { buildAgentSessionKey } = await import("openclaw/plugin-sdk/core");
         const sessionKey = buildAgentSessionKey({
           agentId: api.name,
@@ -50,9 +54,10 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
           channel: relayChannel,
           accountId: relayAccountId,
           sessionKey,
+          instanceId: localInstanceId,
         });
         api.logger.info?.(
-          `[libp2p-mesh] Local identity registered: agent=${api.name}, channel=${relayChannel}, account=${relayAccountId}`,
+          `[libp2p-mesh] Local identity registered: agent=${api.name}, channel=${relayChannel}, account=${relayAccountId}, instanceId=${localInstanceId}`,
         );
 
         // Announce identity to all currently-connected peers
@@ -61,15 +66,34 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
           api.name,
           relayChannel,
           relayAccountId,
+          localInstanceId,
         );
-        const connectedPeers = mesh.getConnectedPeers();
-        for (const peerId of connectedPeers) {
+        for (const peerId of mesh.getConnectedPeers()) {
           try {
             await mesh.sendToPeer(peerId, JSON.stringify(identityMsg));
           } catch {
             // Best-effort; peer may be stale in the connection list
           }
         }
+
+        // When a new peer connects, send our identity to them
+        mesh.onPeerConnect((peerId: string) => {
+          const msg = buildIdentityMessage(
+            localPeerId,
+            api.name,
+            relayChannel,
+            relayAccountId,
+            localInstanceId,
+          );
+          mesh.sendToPeer(peerId, JSON.stringify(msg)).catch(() => {
+            // Best-effort
+          });
+        });
+
+        // When a peer disconnects, clean up the identity map
+        mesh.onPeerDisconnect((peerId: string) => {
+          peerIdentityMap.unregister(peerId);
+        });
       }
 
       // Wire up relay-aware message handler
@@ -78,7 +102,7 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
       });
 
       const identity = mesh.getInstanceIdentity();
-      api.logger.info?.(`[libp2p-mesh] Service started. Peer ID: ${mesh.getLocalPeerId()}`);
+      api.logger.info?.(`[libp2p-mesh] Service started. Peer ID: ${localPeerId}`);
       if (identity) {
         api.logger.info?.(`[libp2p-mesh] Instance Identity: ${identity.id}`);
       }

package/src/types.ts

@@ -116,6 +116,8 @@ export interface MeshNetwork {
   stop(): Promise<void>;
   sendToPeer(peerId: string, message: string): Promise<void>;
   onMessage(handler: (msg: P2PMessage) => void): () => void;
+  onPeerConnect(handler: (peerId: string) => void): () => void;
+  onPeerDisconnect(handler: (peerId: string) => void): () => void;
   publishToTopic(topic: string, message: string): Promise<void>;
   subscribeToTopic(topic: string, handler: (msg: string) => void): Promise<void>;
   getLocalPeerId(): string;