libp2p-mesh 2026.5.12

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "libp2p-mesh",
+  "version": "2026.5.12",
+  "description": "OpenClaw libp2p P2P mesh network plugin for cross-instance agent communication",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build"
+  },
+  "files": [
+    "dist",
+    "index.ts",
+    "api.ts",
+    "src",
+    "openclaw.plugin.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@libp2p/bootstrap": "^10.1.5",
+    "@libp2p/mdns": "^9.0.14",
+    "@libp2p/mplex": "^9.0.12",
+    "@libp2p/noise": "^12.0.1",
+    "@libp2p/peer-id-factory": "^3.0.11",
+    "@libp2p/tcp": "^8.0.13",
+    "@libp2p/websockets": "^8.2.0",
+    "@multiformats/multiaddr": "^12.5.1",
+    "it-length-prefixed": "^10.0.1",
+    "it-pipe": "^3.0.1",
+    "libp2p": "^0.46.16",
+    "uint8arraylist": "^2.4.8"
+  },
+  "devDependencies": {
+    "openclaw": "^2026.5.7",
+    "tsx": "^4.0.0",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.24"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "channel": {
+      "id": "libp2p-mesh",
+      "label": "P2P Mesh",
+      "selectionLabel": "P2P Mesh",
+      "detailLabel": "P2P Mesh",
+      "docsPath": "/channels/libp2p-mesh",
+      "docsLabel": "libp2p-mesh",
+      "blurb": "libp2p mesh network for cross-instance agent communication.",
+      "systemImage": "network"
+    },
+    "install": {
+      "npmSpec": "openclaw-libp2p-mesh",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.24"
+    },
+    "bundle": {
+      "stageRuntimeDependencies": true
+    },
+    "release": {
+      "publishToNpm": true
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./api": {
+      "types": "./dist/api.d.ts",
+      "default": "./dist/api.js"
+    }
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "libp2p",
+    "p2p",
+    "mesh",
+    "decentralized"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lilingfy/openclaw-libp2p-mesh.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lilingfy/openclaw-libp2p-mesh/issues"
+  },
+  "homepage": "https://github.com/lilingfy/openclaw-libp2p-mesh#readme"
+}

package/src/agent-tools.ts

@@ -0,0 +1,116 @@
+import type { MeshNetwork } from "./types.js";
+
+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.",
+      parameters: {
+        type: "object" as const,
+        properties: {
+          peerId: {
+            type: "string" as const,
+            description: "Target peer ID (libp2p Peer ID string)",
+          },
+          message: {
+            type: "string" as const,
+            description: "Message content to send",
+          },
+        },
+        required: ["peerId", "message"],
+      },
+      async execute(_toolCallId: string, params: { peerId: string; message: string }) {
+        try {
+          await mesh.sendToPeer(params.peerId, params.message);
+          return {
+            content: [{ type: "text" as const, text: `Message sent to ${params.peerId}` }],
+            details: { sent: true, peerId: params.peerId },
+          };
+        } catch (err) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Failed to send message to ${params.peerId}: ${String(err)}`,
+              },
+            ],
+            details: { sent: false, peerId: params.peerId, error: String(err) },
+            isError: true,
+          };
+        }
+      },
+    },
+    {
+      name: "p2p_broadcast",
+      label: "P2P Broadcast",
+      description: "Broadcast a message to all peers on a topic via the P2P mesh network.",
+      parameters: {
+        type: "object" as const,
+        properties: {
+          topic: {
+            type: "string" as const,
+            description: "Topic name to broadcast on",
+          },
+          message: {
+            type: "string" as const,
+            description: "Message content to broadcast",
+          },
+        },
+        required: ["topic", "message"],
+      },
+      async execute(_toolCallId: string, params: { topic: string; message: string }) {
+        try {
+          await mesh.publishToTopic(params.topic, params.message);
+          return {
+            content: [{ type: "text" as const, text: `Broadcast sent to topic ${params.topic}` }],
+            details: { broadcast: true, topic: params.topic },
+          };
+        } catch (err) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Failed to broadcast to topic ${params.topic}: ${String(err)}`,
+              },
+            ],
+            details: { broadcast: false, topic: params.topic, error: String(err) },
+            isError: true,
+          };
+        }
+      },
+    },
+    {
+      name: "p2p_list_peers",
+      label: "P2P List Peers",
+      description: "List currently connected peers in the P2P mesh network.",
+      parameters: {
+        type: "object" as const,
+        properties: {},
+      },
+      async execute(_toolCallId: string) {
+        try {
+          const peers = mesh.getConnectedPeers();
+          const text =
+            peers.length === 0
+              ? "No peers currently connected."
+              : `Connected peers (${peers.length}): ${peers.join(", ")}`;
+          return {
+            content: [{ type: "text" as const, text }],
+            details: {
+              localPeerId: mesh.getLocalPeerId(),
+              connectedPeers: peers,
+              count: peers.length,
+            },
+          };
+        } catch (err) {
+          return {
+            content: [{ type: "text" as const, text: `Failed to list peers: ${String(err)}` }],
+            details: { error: String(err) },
+            isError: true,
+          };
+        }
+      },
+    },
+  ];
+}

package/src/channel.ts

@@ -0,0 +1,68 @@
+import { createChatChannelPlugin } from "openclaw/plugin-sdk/core";
+import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
+import type { MeshNetwork, MeshAccount } from "./types.js";
+import { sendViaMesh } from "./send.js";
+
+export function createLibp2pMeshChannel(mesh: MeshNetwork): ChannelPlugin {
+  return createChatChannelPlugin<MeshAccount>({
+    base: {
+      id: "libp2p-mesh",
+      meta: {
+        id: "libp2p-mesh",
+        label: "P2P Mesh",
+        selectionLabel: "P2P Mesh",
+        docsPath: "/channels/libp2p-mesh",
+        docsLabel: "libp2p-mesh",
+        blurb: "libp2p mesh network for cross-instance agent communication.",
+        systemImage: "network",
+      },
+      capabilities: {
+        chatTypes: ["direct"],
+        media: false,
+        blockStreaming: false,
+      },
+      configSchema: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {},
+        },
+      },
+      config: {
+        listAccountIds: () => ["default"],
+        resolveAccount: () => ({
+          accountId: "default",
+          configured: true,
+          enabled: true,
+        }),
+        isConfigured: () => true,
+        isEnabled: () => true,
+        describeAccount: () => ({
+          accountId: "default",
+          name: "default",
+          configured: true,
+          enabled: true,
+          connected: mesh.getConnectedPeers().length > 0,
+        }),
+      },
+      messaging: {
+        normalizeTarget: (raw: string) => raw.trim(),
+        targetResolver: {
+          looksLikeId: () => true,
+          hint: "peer-id",
+        },
+      },
+    },
+    outbound: {
+      deliveryMode: "gateway",
+      sendText: async ({ to, text }) => {
+        try {
+          await sendViaMesh(mesh, to, text);
+          return { channel: "libp2p-mesh", messageId: `p2p-${Date.now()}` };
+        } catch (err) {
+          return { channel: "libp2p-mesh", messageId: `p2p-${Date.now()}`, meta: { error: String(err) } };
+        }
+      },
+    },
+  }) as ChannelPlugin;
+}

package/src/discovery.ts

@@ -0,0 +1,13 @@
+import type { MeshConfig } from "./types.js";
+
+export function resolveDiscoveryConfig(config?: MeshConfig): {
+  enabled: boolean;
+  mechanism: "mdns" | "bootstrap" | "dht";
+  bootstrapList: string[];
+} {
+  return {
+    enabled: true,
+    mechanism: config?.discovery ?? "mdns",
+    bootstrapList: config?.bootstrapList ?? [],
+  };
+}

package/src/inbound.ts

@@ -0,0 +1,31 @@
+import type { P2PMessage } from "./types.js";
+
+export type InboundHandlerDeps = {
+  logger?: {
+    info?: (msg: string) => void;
+    debug?: (msg: string) => void;
+    warn?: (msg: string) => void;
+    error?: (msg: string) => void;
+  };
+  sendToChannel?: (channelId: string, target: string, text: string) => Promise<void>;
+};
+
+export function handleP2PInbound(msg: P2PMessage, deps: InboundHandlerDeps): void {
+  const { logger, sendToChannel } = deps;
+  if (msg.type === "broadcast") {
+    logger?.info?.(`[libp2p-mesh] Broadcast from ${msg.from} on topic ${msg.topic ?? "(none)"}: ${msg.payload}`);
+    return;
+  }
+
+  // Direct message — log and forward to local channel
+  logger?.info?.(`[libp2p-mesh] Direct message from ${msg.from}: ${msg.payload}`);
+
+  if (!sendToChannel || !msg.payload) {
+    return;
+  }
+
+  const text = `[来自 ${msg.from}]\n${msg.payload}`;
+  sendToChannel("libp2p-mesh", msg.from, text).catch((err) => {
+    logger?.error?.(`[libp2p-mesh] Failed to forward direct message from ${msg.from}: ${err}`);
+  });
+}

package/src/mesh.ts

@@ -0,0 +1,338 @@
+// Polyfill for Node.js < 22 (libp2p dependencies use Promise.withResolvers)
+if (!Promise.withResolvers) {
+  Promise.withResolvers = function <T>() {
+    let resolve: (value?: T | PromiseLike<T> | undefined) => void;
+    let reject: (reason?: unknown) => void;
+    const promise = new Promise<T>((res, rej) => {
+      resolve = res as typeof resolve;
+      reject = rej;
+    });
+    return { promise, resolve: resolve!, reject: reject! };
+  };
+}
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { mdns } from "@libp2p/mdns";
+import { mplex } from "@libp2p/mplex";
+import { noise } from "@libp2p/noise";
+import {
+  createEd25519PeerId,
+  createFromProtobuf,
+  exportToProtobuf,
+} from "@libp2p/peer-id-factory";
+import { tcp } from "@libp2p/tcp";
+import { webSockets } from "@libp2p/websockets";
+import { bootstrap } from "@libp2p/bootstrap";
+import { encode, decode } from "it-length-prefixed";
+import { pipe } from "it-pipe";
+import { createLibp2p } from "libp2p";
+import { Uint8ArrayList } from "uint8arraylist";
+import type { Libp2p } from "libp2p";
+import type { MeshConfig, MeshNetwork, P2PMessage } from "./types.js";
+
+const PROTOCOL = "/openclaw-msg/1.0.0";
+const MAX_SEEN_MESSAGES = 1000;
+
+function resolvePeerIdPath(customPath?: string): string {
+  if (customPath) return customPath;
+  const stateDir = process.env.OPENCLAW_STATE_DIR;
+  if (stateDir) {
+    return path.join(stateDir, "libp2p", "peer-id.json");
+  }
+  return path.join(homedir(), ".openclaw", "libp2p", "peer-id.json");
+}
+
+async function loadOrCreatePeerId(customPath?: string): Promise<ReturnType<typeof createEd25519PeerId> extends Promise<infer T> ? T : never> {
+  const peerIdPath = resolvePeerIdPath(customPath);
+  try {
+    const saved = JSON.parse(await readFile(peerIdPath, "utf8")) as { protobuf: string };
+    const peerId = await createFromProtobuf(Buffer.from(saved.protobuf, "base64"));
+    return peerId as ReturnType<typeof createEd25519PeerId> extends Promise<infer T> ? T : never;
+  } catch {
+    const peerId = await createEd25519PeerId();
+    const protobuf = Buffer.from(exportToProtobuf(peerId)).toString("base64");
+    await mkdir(path.dirname(peerIdPath), { recursive: true });
+    await writeFile(peerIdPath, JSON.stringify({ protobuf }, null, 2));
+    return peerId;
+  }
+}
+
+export function createMeshNetwork(options: {
+  config?: MeshConfig;
+  logger?: { info?: (msg: string) => void; debug?: (msg: string) => void; warn?: (msg: string) => void; error?: (msg: string) => void };
+}): MeshNetwork {
+  const config = options.config ?? {};
+  const logger = options.logger;
+
+  // Use an object property instead of a bare `let` so all closures share
+  // the same mutable reference even if the bundler rewrites scopes.
+  const state = {
+    node: null as Libp2p | null,
+  };
+
+  const seenMessages = new Set<string>();
+  const messageHandlers = new Set<(msg: P2PMessage) => void>();
+  const topicHandlers = new Map<string, Set<(msg: string) => void>>();
+
+  async function start(): Promise<void> {
+    const peerId = await loadOrCreatePeerId(config.peerIdPath);
+
+    // Build transports dynamically
+    const transports: any[] = [tcp()];
+    if (config.enableWebSocket) {
+      transports.push(webSockets());
+    }
+
+    // Build peer discovery dynamically
+    const peerDiscovery: any[] = [];
+    const discoveryMechanism = config.discovery ?? "mdns";
+    if (discoveryMechanism === "mdns") {
+      peerDiscovery.push(mdns({ interval: 1000 }));
+      logger?.info?.("[libp2p-mesh] Using mDNS discovery (LAN)");
+    } else if (discoveryMechanism === "bootstrap") {
+      const bootstrapList = config.bootstrapList ?? [];
+      if (bootstrapList.length > 0) {
+        peerDiscovery.push(bootstrap({ list: bootstrapList }));
+        logger?.info?.(`[libp2p-mesh] Using bootstrap discovery (${bootstrapList.length} node(s))`);
+      } else {
+        logger?.warn?.("[libp2p-mesh] discovery=bootstrap but bootstrapList is empty; falling back to mDNS");
+        peerDiscovery.push(mdns({ interval: 1000 }));
+      }
+    } else if (discoveryMechanism === "dht") {
+      logger?.warn?.("[libp2p-mesh] DHT discovery is not yet implemented; falling back to mDNS");
+      peerDiscovery.push(mdns({ interval: 1000 }));
+    }
+
+    state.node = await createLibp2p({
+      peerId,
+      start: false,
+      transports,
+      connectionEncryption: [noise()],
+      streamMuxers: [mplex()],
+      addresses: {
+        listen: config.listenAddrs ?? ["/ip4/0.0.0.0/tcp/0"],
+      },
+      peerDiscovery,
+    });
+
+    state.node.addEventListener("peer:connect", (evt) => {
+      const peerIdStr = evt.detail.toString();
+      logger?.debug?.(`[libp2p-mesh] Peer connected: ${peerIdStr}`);
+    });
+
+    state.node.addEventListener("peer:disconnect", (evt) => {
+      const peerIdStr = evt.detail.toString();
+      logger?.debug?.(`[libp2p-mesh] Peer disconnected: ${peerIdStr}`);
+    });
+
+    await state.node.handle(PROTOCOL, async ({ stream, connection }) => {
+      try {
+        await pipe(
+          stream.source,
+          decode,
+          async (source) => {
+            for await (const msg of source) {
+              const data = new TextDecoder().decode(msg.subarray());
+              let parsed: P2PMessage;
+              try {
+                parsed = JSON.parse(data) as P2PMessage;
+              } catch {
+                logger?.warn?.(`[libp2p-mesh] Failed to parse message from ${connection.remotePeer.toString()}`);
+                continue;
+              }
+
+              if (seenMessages.has(parsed.id)) {
+                continue;
+              }
+              if (seenMessages.size >= MAX_SEEN_MESSAGES) {
+                seenMessages.clear();
+              }
+              seenMessages.add(parsed.id);
+
+              // Enrich with local timestamp if missing
+              if (!parsed.timestamp) {
+                parsed.timestamp = Date.now();
+              }
+
+              logger?.debug?.(`[libp2p-mesh] Received ${parsed.type} from ${parsed.from}`);
+
+              // Notify direct message handlers
+              for (const handler of messageHandlers) {
+                try {
+                  handler(parsed);
+                } catch (err) {
+                  logger?.error?.(`[libp2p-mesh] Message handler error: ${String(err)}`);
+                }
+              }
+
+              // Handle broadcast / topic subscription
+              if (parsed.type === "broadcast" && parsed.topic) {
+                const handlers = topicHandlers.get(parsed.topic);
+                if (handlers) {
+                  for (const h of handlers) {
+                    try {
+                      h(parsed.payload);
+                    } catch (err) {
+                      logger?.error?.(`[libp2p-mesh] Topic handler error: ${String(err)}`);
+                    }
+                  }
+                }
+                // Flood-fill forward to other connected peers (with TTL guard)
+                await forwardBroadcast(parsed, connection.remotePeer.toString());
+              }
+            }
+          },
+        );
+      } catch (err) {
+        logger?.error?.(`[libp2p-mesh] Protocol handler error: ${String(err)}`);
+      }
+    });
+
+    await state.node.start();
+
+    logger?.info?.(`[libp2p-mesh] Node started. Peer ID: ${state.node.peerId.toString()}`);
+    logger?.info?.(`[libp2p-mesh] Listening on: ${state.node.getMultiaddrs().map((ma) => ma.toString()).join(", ")}`);
+  }
+
+  async function stop(): Promise<void> {
+    if (state.node) {
+      await state.node.stop();
+      state.node = null;
+      logger?.info?.("[libp2p-mesh] Node stopped.");
+    }
+  }
+
+  async function sendToPeer(peerId: string, message: string): Promise<void> {
+    if (!state.node) {
+      throw new Error("Mesh network is not started");
+    }
+
+    const msg: P2PMessage = {
+      id: crypto.randomUUID(),
+      type: "direct",
+      from: state.node.peerId.toString(),
+      to: peerId,
+      payload: message,
+      timestamp: Date.now(),
+    };
+
+    const data = new TextEncoder().encode(JSON.stringify(msg));
+
+    const abortController = new AbortController();
+    const timeout = setTimeout(() => abortController.abort(), 8000);
+
+    try {
+      const { peerIdFromString } = await import("@libp2p/peer-id");
+      logger?.debug?.(`[libp2p-mesh] dialProtocol to ${peerId}`);
+      const stream = await state.node.dialProtocol(peerIdFromString(peerId) as any, PROTOCOL, {
+        signal: abortController.signal,
+      });
+      if (!stream) {
+        throw new Error(`Failed to establish stream to ${peerId}; peer may be unreachable`);
+      }
+      logger?.debug?.(`[libp2p-mesh] stream opened to ${peerId}`);
+      await pipe([new Uint8ArrayList(data)], encode, stream.sink);
+      logger?.debug?.(`[libp2p-mesh] message sent to ${peerId}`);
+    } catch (err) {
+      logger?.error?.(`[libp2p-mesh] sendToPeer error: ${String(err)}`);
+      if (abortController.signal.aborted) {
+        throw new Error(`Send to ${peerId} timed out after 8s`);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  async function publishToTopic(topic: string, message: string): Promise<void> {
+    if (!state.node) {
+      throw new Error("Mesh network is not started");
+    }
+
+    const msg: P2PMessage = {
+      id: crypto.randomUUID(),
+      type: "broadcast",
+      from: state.node.peerId.toString(),
+      topic,
+      payload: message,
+      timestamp: Date.now(),
+    };
+
+    const data = new TextEncoder().encode(JSON.stringify(msg));
+    const connections = state.node.getConnections();
+    let sent = 0;
+
+    for (const conn of connections) {
+      const abortController = new AbortController();
+      const timeout = setTimeout(() => abortController.abort(), 5000);
+      try {
+        const stream = await conn.newStream(PROTOCOL, { signal: abortController.signal });
+        await pipe([new Uint8ArrayList(data)], encode, stream.sink);
+        sent++;
+      } catch {
+        // Ignore individual forwarding errors
+      } finally {
+        clearTimeout(timeout);
+      }
+    }
+
+    logger?.debug?.(`[libp2p-mesh] Broadcast sent to ${sent} peer(s) on topic ${topic}`);
+  }
+
+  async function forwardBroadcast(msg: P2PMessage, fromPeerId: string): Promise<void> {
+    if (!state.node) return;
+    // Simple flood-fill: forward to all connected peers except the sender
+    const data = new TextEncoder().encode(JSON.stringify(msg));
+    for (const conn of state.node.getConnections()) {
+      const remotePeerId = conn.remotePeer.toString();
+      if (remotePeerId === fromPeerId) continue;
+      const abortController = new AbortController();
+      const timeout = setTimeout(() => abortController.abort(), 5000);
+      try {
+        const stream = await conn.newStream(PROTOCOL, { signal: abortController.signal });
+        await pipe([new Uint8ArrayList(data)], encode, stream.sink);
+      } catch {
+        // Ignore forwarding errors
+      } finally {
+        clearTimeout(timeout);
+      }
+    }
+  }
+
+  function onMessage(handler: (msg: P2PMessage) => void): () => void {
+    messageHandlers.add(handler);
+    return () => {
+      messageHandlers.delete(handler);
+    };
+  }
+
+  async function subscribeToTopic(topic: string, handler: (msg: string) => void): Promise<void> {
+    if (!topicHandlers.has(topic)) {
+      topicHandlers.set(topic, new Set());
+    }
+    topicHandlers.get(topic)!.add(handler);
+  }
+
+  function getLocalPeerId(): string {
+    return state.node?.peerId.toString() ?? "";
+  }
+
+  function getConnectedPeers(): string[] {
+    if (!state.node) return [];
+    const peers = state.node.getConnections().map((c) => c.remotePeer.toString());
+    return [...new Set(peers)];
+  }
+
+  return {
+    start,
+    stop,
+    sendToPeer,
+    onMessage,
+    publishToTopic,
+    subscribeToTopic,
+    getLocalPeerId,
+    getConnectedPeers,
+  };
+}