libp2p-mesh 2026.5.30 → 2026.5.32

package/dist/src/identity-exchange.js

@@ -9,6 +9,7 @@ export function buildIdentityMessage(peerId, agentId, channel, accountId, instan
 }
 export async function handleIdentityMessage(msg, deps) {
     const logger = deps.logger;
+    logger?.debug?.(`[libp2p-mesh] handleIdentityMessage: from=${msg.from}, type=${msg.type}, payload_prefix=${msg.payload.slice(0, 60)}`);
     // Parse remote identity payload
     let parsed = {};
     try {
@@ -31,6 +32,7 @@ export async function handleIdentityMessage(msg, deps) {
         }
     }
     const { agentId, channel, accountId, instanceId } = parsed;
+    logger?.debug?.(`[libp2p-mesh] handleIdentityMessage: parsed agentId=${agentId}, channel=${channel}, accountId=${accountId}, instanceId=${instanceId}`);
     // Only register if all required fields are present
     if (agentId && channel && accountId) {
         const { buildAgentSessionKey } = await import("openclaw/plugin-sdk/core");
@@ -46,6 +48,7 @@ export async function handleIdentityMessage(msg, deps) {
         // process exits before the next save cycle.
         await deps.peerIdentityMap.saveNow();
         logger?.info?.(`[libp2p-mesh] Registered peer identity: ${msg.from} (agent=${agentId}, channel=${channel}, instanceId=${instanceId ?? "n/a"})`);
+        logger?.debug?.(`[libp2p-mesh] handleIdentityMessage: successfully registered ${msg.from}, now sending reply to ${msg.from}`);
     }
     // Send local identity back to the remote peer.
     // We intentionally do NOT await this — the send callback (and any
@@ -54,6 +57,7 @@ export async function handleIdentityMessage(msg, deps) {
     // blocks the caller; the recipient's handler will persist the reply on
     // its own via saveNow().
     const localIdentity = buildIdentityMessage(deps.localPeerId, deps.localAgentId, deps.localChannel, deps.localAccountId, deps.localInstanceId);
+    logger?.debug?.(`[libp2p-mesh] handleIdentityMessage: sending identity reply to ${msg.from}`);
     deps.send(msg.from, localIdentity).catch((sendErr) => {
         logger?.warn?.(`[libp2p-mesh] Failed to send identity reply to ${msg.from}: ${String(sendErr)}`);
     });

package/dist/src/inbound.js

@@ -41,6 +41,7 @@ export async function handleP2PInbound(msg, deps) {
             // Delegate full identity exchange (register + send reply) to the
             // dedicated handler.  This ensures bidirectional identity propagation,
             // forced persistence via saveNow(), and proper logging.
+            logger?.debug?.(`[libp2p-mesh] handleP2PInbound: processing identity from ${msg.from}`);
             try {
                 await handleIdentityMessage(msg, {
                     peerIdentityMap: deps.peerIdentityMap,

package/dist/src/mesh.js

@@ -333,7 +333,9 @@ export function createMeshNetwork(options) {
             runOnTransientConnection: true,
         });
         await state.node.start();
-        // Wait for DHT routing table to populate before registering pubkey
+        // Wait for DHT routing table to populate before registering pubkey.
+        // Non-blocking: we don't await the pubkey registration here — it runs
+        // in the background so the node can start serving messages immediately.
         if (enableDHT) {
             const dht = getDHTService();
             if (dht) {
@@ -353,7 +355,12 @@ export function createMeshNetwork(options) {
                     logger?.warn?.(`[libp2p-mesh] DHT routing table still empty after ${maxAttempts}s; continuing anyway`);
                 }
                 if (state.instanceIdentity) {
-                    await registerPubkey(dht, state.instanceIdentity.id, state.instanceIdentity.pubkey, logger).catch(() => {
+                    // Fire-and-forget: pubkey registration is best-effort. In LAN
+                    // scenarios with mDNS, peers connect directly and don't need DHT
+                    // pubkey lookup to exchange identities. The registration will
+                    // succeed once the DHT routing table populates (e.g. when a
+                    // bootstrap peer is discovered or another DHT node joins).
+                    registerPubkey(dht, state.instanceIdentity.id, state.instanceIdentity.pubkey, logger).catch(() => {
                         // Already logged inside registerPubkey
                     });
                 }

package/dist/src/plugin.js

@@ -26,6 +26,12 @@ export function registerLibp2pMesh(api) {
             // peers connect during mesh.start() (mDNS can fire peer:connect
             // before this function's sequential code reaches onPeerConnect).
             await peerIdentityMap.load();
+            // Queue identity sends during mesh.start() so they are flushed only
+            // after the node is fully ready (protocol handler registered, DHT
+            // initialized, etc.).  Sending inside onPeerConnect during startup
+            // races with node initialization and can cause the remote peer's
+            // reply to be lost or unprocessed.
+            const pendingIdentityPeers = new Set();
             await mesh.start();
             const instanceIdentity = mesh.getInstanceIdentity();
             const localInstanceId = instanceIdentity?.id;
@@ -79,15 +85,21 @@ export function registerLibp2pMesh(api) {
             mesh.onMessage((msg) => {
                 handleP2PInbound(msg, buildInboundDeps());
             });
-            // Always send our identity when a peer connects. Identity exchange is
-            // bidirectional: even if we already know this peer, they may not know
-            // our current identity (or theirs may be stale). The receiving side
-            // handles dedup via handleIdentityMessage (register only if new or
-            // updated). Removing the send-side dedup ensures both sides always
-            // have each other's current identity.
+            // Always send our identity when a peer connects. During mesh.start(),
+            // mDNS can fire peer:connect before the node is fully ready (protocol
+            // handler just registered, DHT still initializing). Sending identity
+            // messages at that point can cause the remote peer's reply to arrive
+            // before we're ready to process it, breaking the identity exchange.
+            // Queue during startup; flush after start() + send directly thereafter.
+            let startupComplete = false;
             mesh.onPeerConnect((peerId) => {
+                if (!startupComplete) {
+                    // During startup: queue, don't send yet
+                    pendingIdentityPeers.add(peerId);
+                    return;
+                }
+                // After startup: send directly
                 api.logger.info?.(`[libp2p-mesh] Peer connected: ${peerId} — sending identity`);
-                // Only send identity if relay config is set
                 if (!relayChannel || !relayAccountId)
                     return;
                 const msg = JSON.stringify({
@@ -141,6 +153,38 @@ export function registerLibp2pMesh(api) {
             if (nat.reservedRelays.length > 0) {
                 api.logger.info?.(`[libp2p-mesh] Active relay reservations: ${nat.reservedRelays.join(", ")}`);
             }
+            // Flush identity messages that were queued during mesh.start().
+            // Peers that connected during startup (mDNS-triggered peer:connect
+            // inside start()) are in pendingIdentityPeers. Send now that the
+            // node is fully ready.
+            startupComplete = true;
+            const flushPendingIdentities = () => {
+                if (!relayChannel || !relayAccountId)
+                    return;
+                const identityMsg = JSON.stringify({
+                    id: crypto.randomUUID(),
+                    type: "identity",
+                    from: mesh.getLocalPeerId(),
+                    payload: JSON.stringify({
+                        agentId: api.name,
+                        channel: relayChannel,
+                        accountId: relayAccountId,
+                        instanceId: localInstanceId,
+                    }),
+                    timestamp: Date.now(),
+                });
+                for (const peerId of pendingIdentityPeers) {
+                    if (peerIdentityMap.hasIdentity(peerId)) {
+                        api.logger.debug?.(`[libp2p-mesh] Peer ${peerId} already known (loaded from disk), skipping queued identity`);
+                        continue;
+                    }
+                    mesh.sendToPeer(peerId, identityMsg).catch(() => { });
+                }
+                pendingIdentityPeers.clear();
+            };
+            if (pendingIdentityPeers.size > 0) {
+                flushPendingIdentities();
+            }
         },
         stop: async () => {
             await mesh.stop();

package/package.json

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

package/src/identity-exchange.ts

@@ -38,6 +38,7 @@ export async function handleIdentityMessage(
   deps: IdentityExchangeDeps,
 ): Promise<void> {
   const logger = deps.logger;
+  logger?.debug?.(`[libp2p-mesh] handleIdentityMessage: from=${msg.from}, type=${msg.type}, payload_prefix=${msg.payload.slice(0, 60)}`);
 
   // Parse remote identity payload
   let parsed: Record<string, unknown> = {};
@@ -66,6 +67,7 @@ export async function handleIdentityMessage(
     accountId?: string;
     instanceId?: string;
   };
+  logger?.debug?.(`[libp2p-mesh] handleIdentityMessage: parsed agentId=${agentId}, channel=${channel}, accountId=${accountId}, instanceId=${instanceId}`);
 
   // Only register if all required fields are present
   if (agentId && channel && accountId) {
@@ -84,6 +86,7 @@ export async function handleIdentityMessage(
     logger?.info?.(
       `[libp2p-mesh] Registered peer identity: ${msg.from} (agent=${agentId}, channel=${channel}, instanceId=${instanceId ?? "n/a"})`,
     );
+    logger?.debug?.(`[libp2p-mesh] handleIdentityMessage: successfully registered ${msg.from}, now sending reply to ${msg.from}`);
   }
 
   // Send local identity back to the remote peer.
@@ -99,6 +102,7 @@ export async function handleIdentityMessage(
     deps.localAccountId,
     deps.localInstanceId,
   );
+  logger?.debug?.(`[libp2p-mesh] handleIdentityMessage: sending identity reply to ${msg.from}`);
   deps.send(msg.from, localIdentity).catch((sendErr) => {
     logger?.warn?.(
       `[libp2p-mesh] Failed to send identity reply to ${msg.from}: ${String(sendErr)}`,

package/src/inbound.ts

@@ -60,6 +60,7 @@ export async function handleP2PInbound(msg: P2PMessage, deps?: InboundHandlerDep
       // Delegate full identity exchange (register + send reply) to the
       // dedicated handler.  This ensures bidirectional identity propagation,
       // forced persistence via saveNow(), and proper logging.
+      logger?.debug?.(`[libp2p-mesh] handleP2PInbound: processing identity from ${msg.from}`);
       try {
         await handleIdentityMessage(msg, {
           peerIdentityMap: deps.peerIdentityMap,

package/src/mesh.ts

@@ -388,7 +388,9 @@ export function createMeshNetwork(options: {
 
     await state.node.start();
 
-    // Wait for DHT routing table to populate before registering pubkey
+    // Wait for DHT routing table to populate before registering pubkey.
+    // Non-blocking: we don't await the pubkey registration here — it runs
+    // in the background so the node can start serving messages immediately.
     if (enableDHT) {
       const dht = getDHTService();
       if (dht) {
@@ -409,9 +411,16 @@ export function createMeshNetwork(options: {
         }
 
         if (state.instanceIdentity) {
-          await registerPubkey(dht, state.instanceIdentity.id, state.instanceIdentity.pubkey, logger).catch(() => {
-            // Already logged inside registerPubkey
-          });
+          // Fire-and-forget: pubkey registration is best-effort. In LAN
+          // scenarios with mDNS, peers connect directly and don't need DHT
+          // pubkey lookup to exchange identities. The registration will
+          // succeed once the DHT routing table populates (e.g. when a
+          // bootstrap peer is discovered or another DHT node joins).
+          registerPubkey(dht, state.instanceIdentity.id, state.instanceIdentity.pubkey, logger).catch(
+            () => {
+              // Already logged inside registerPubkey
+            },
+          );
         }
       }
     }

package/src/plugin.ts

@@ -35,6 +35,13 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
       // before this function's sequential code reaches onPeerConnect).
       await peerIdentityMap.load();
 
+      // Queue identity sends during mesh.start() so they are flushed only
+      // after the node is fully ready (protocol handler registered, DHT
+      // initialized, etc.).  Sending inside onPeerConnect during startup
+      // races with node initialization and can cause the remote peer's
+      // reply to be lost or unprocessed.
+      const pendingIdentityPeers = new Set<string>();
+
       await mesh.start();
 
       const instanceIdentity = mesh.getInstanceIdentity();
@@ -94,15 +101,22 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
         handleP2PInbound(msg, buildInboundDeps());
       });
 
-      // Always send our identity when a peer connects. Identity exchange is
-      // bidirectional: even if we already know this peer, they may not know
-      // our current identity (or theirs may be stale). The receiving side
-      // handles dedup via handleIdentityMessage (register only if new or
-      // updated). Removing the send-side dedup ensures both sides always
-      // have each other's current identity.
+      // Always send our identity when a peer connects. During mesh.start(),
+      // mDNS can fire peer:connect before the node is fully ready (protocol
+      // handler just registered, DHT still initializing). Sending identity
+      // messages at that point can cause the remote peer's reply to arrive
+      // before we're ready to process it, breaking the identity exchange.
+      // Queue during startup; flush after start() + send directly thereafter.
+      let startupComplete = false;
+
       mesh.onPeerConnect((peerId: string) => {
+        if (!startupComplete) {
+          // During startup: queue, don't send yet
+          pendingIdentityPeers.add(peerId);
+          return;
+        }
+        // After startup: send directly
         api.logger.info?.(`[libp2p-mesh] Peer connected: ${peerId} — sending identity`);
-        // Only send identity if relay config is set
         if (!relayChannel || !relayAccountId) return;
         const msg = JSON.stringify({
           id: crypto.randomUUID(),
@@ -161,6 +175,39 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
           `[libp2p-mesh] Active relay reservations: ${nat.reservedRelays.join(", ")}`,
         );
       }
+
+      // Flush identity messages that were queued during mesh.start().
+      // Peers that connected during startup (mDNS-triggered peer:connect
+      // inside start()) are in pendingIdentityPeers. Send now that the
+      // node is fully ready.
+      startupComplete = true;
+      const flushPendingIdentities = () => {
+        if (!relayChannel || !relayAccountId) return;
+        const identityMsg = JSON.stringify({
+          id: crypto.randomUUID(),
+          type: "identity",
+          from: mesh.getLocalPeerId(),
+          payload: JSON.stringify({
+            agentId: api.name,
+            channel: relayChannel,
+            accountId: relayAccountId,
+            instanceId: localInstanceId,
+          }),
+          timestamp: Date.now(),
+        });
+        for (const peerId of pendingIdentityPeers) {
+          if (peerIdentityMap.hasIdentity(peerId)) {
+            api.logger.debug?.(`[libp2p-mesh] Peer ${peerId} already known (loaded from disk), skipping queued identity`);
+            continue;
+          }
+          mesh.sendToPeer(peerId, identityMsg).catch(() => {});
+        }
+        pendingIdentityPeers.clear();
+      };
+
+      if (pendingIdentityPeers.size > 0) {
+        flushPendingIdentities();
+      }
     },
     stop: async () => {
       await mesh.stop();