libp2p-mesh 2026.5.12

package/src/plugin.ts

@@ -0,0 +1,96 @@
+import type { OpenClawPluginApi, PluginCommandContext, PluginCommandResult } from "openclaw/plugin-sdk/core";
+import { createLibp2pMeshChannel } from "./channel.js";
+import { handleP2PInbound, type InboundHandlerDeps } from "./inbound.js";
+import { createMeshNetwork } from "./mesh.js";
+import { buildP2PTools } from "./agent-tools.js";
+import { sendViaMesh } from "./send.js";
+import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
+
+export function registerLibp2pMesh(api: OpenClawPluginApi) {
+  const mesh = createMeshNetwork({
+    config: api.pluginConfig as { listenAddrs?: string[]; discovery?: "mdns" | "bootstrap" | "dht"; bootstrapList?: string[]; meshTopic?: string; enableAgentSync?: boolean; enableWebSocket?: boolean } | undefined,
+    logger: api.logger,
+  });
+
+  const channel = createLibp2pMeshChannel(mesh);
+
+  // 1. Register Service (manages libp2p node lifecycle)
+  api.registerService({
+    id: "libp2p-mesh",
+    start: async () => {
+      api.logger.info?.("[libp2p-mesh] >>> Service start called");
+      await mesh.start();
+      api.logger.info?.(`[libp2p-mesh] >>> mesh.start() done, Peer ID: ${mesh.getLocalPeerId()}`);
+      mesh.onMessage((msg) => {
+        api.logger.info?.("[libp2p-mesh] >>> onMessage handler registered");
+        const sendToChannel: InboundHandlerDeps["sendToChannel"] = async (_channelId, target, text) => {
+          try {
+            await sendViaMesh(mesh, target, text);
+          } catch (err) {
+            api.logger.error?.(`[libp2p-mesh] sendToChannel error: ${err}`);
+          }
+        };
+        handleP2PInbound(msg, { logger: api.logger, sendToChannel });
+      });
+      api.logger.info?.(`[libp2p-mesh] Service started. Peer ID: ${mesh.getLocalPeerId()}`);
+    },
+    stop: async () => {
+      await mesh.stop();
+      api.logger.info?.("[libp2p-mesh] Service stopped.");
+    },
+  });
+
+  // 2. Register Channel (lightweight debugging surface)
+  api.registerChannel({
+    plugin: channel as ChannelPlugin,
+  });
+
+  // 3. Register Agent Tools
+  const tools = buildP2PTools(mesh);
+  for (const tool of tools) {
+    api.registerTool(tool as never);
+  }
+
+  // 4. Register Command (injects agent prompt guidance so the LLM knows to use
+  //    p2p_list_peers / p2p_send_message / p2p_broadcast for P2P mesh operations
+  //    instead of the built-in `nodes` tool, which only manages OpenClaw paired nodes.)
+  api.registerCommand({
+    name: "p2p",
+    description: "P2P mesh network operations (list peers, send messages, broadcast).",
+    agentPromptGuidance: [
+      "When the user asks to list, show, or discover P2P mesh peers or connected agents, use the p2p_list_peers tool. Do NOT use the built-in `nodes` tool for this — `nodes` lists OpenClaw paired nodes, not P2P mesh peers.",
+      "When the user asks to send a direct message to another peer/agent, use p2p_send_message.",
+      "When the user asks to broadcast a message to all peers on a topic, use p2p_broadcast.",
+    ],
+    handler: (_ctx: PluginCommandContext): PluginCommandResult => {
+      return { text: "P2P mesh tools are available. Use p2p_list_peers, p2p_send_message, or p2p_broadcast." };
+    },
+  });
+
+  // 5. Register CLI commands for operator access
+  api.registerCli(
+    (ctx) => {
+      ctx.program
+        .command("status")
+        .description("Show local peer ID and connected peers")
+        .action(async () => {
+          const peers = mesh.getConnectedPeers();
+          ctx.logger.info?.(`Local Peer ID: ${mesh.getLocalPeerId()}\nConnected peers (${peers.length}): ${peers.join(", ") || "none"}`);
+        });
+      ctx.program
+        .command("peers")
+        .description("Alias for mesh status — list connected peers")
+        .action(async () => {
+          const peers = mesh.getConnectedPeers();
+          ctx.logger.info?.(`Connected peers (${peers.length}): ${peers.join(", ") || "none"}`);
+        });
+    },
+    { parentPath: ["p2p"] },
+  );
+
+  // 6. Register Hook (log received messages for observability)
+  api.registerHook("message:received", async (event) => {
+    const ctx = event.context as { channelId?: string } | undefined;
+    api.logger.debug?.(`[libp2p-mesh] message received on channel ${ctx?.channelId ?? "unknown"}`);
+  }, { name: "libp2p-mesh-message-received" });
+}

package/src/pubsub.ts

@@ -0,0 +1,17 @@
+import type { MeshNetwork } from "./types.js";
+
+export async function broadcastToMesh(mesh: MeshNetwork, topic: string, message: string): Promise<void> {
+  await mesh.publishToTopic(topic, message);
+}
+
+export async function subscribeToMeshTopic(
+  mesh: MeshNetwork,
+  topic: string,
+  handler: (msg: string) => void,
+): Promise<() => void> {
+  await mesh.subscribeToTopic(topic, handler);
+  return () => {
+    // Unsubscribe is not directly supported in the current MeshNetwork interface;
+    // the handler reference could be stored externally for future cleanup.
+  };
+}

package/src/send.ts

@@ -0,0 +1,11 @@
+import type { MeshNetwork } from "./types.js";
+
+export async function sendViaMesh(mesh: MeshNetwork, peerId: string, text: string): Promise<void> {
+  if (!peerId || !peerId.trim()) {
+    throw new Error("Peer ID is required");
+  }
+  if (!text || !text.trim()) {
+    throw new Error("Message text is required");
+  }
+  await mesh.sendToPeer(peerId.trim(), text.trim());
+}

package/src/types.ts

@@ -0,0 +1,36 @@
+export interface P2PMessage {
+  id: string;
+  type: "direct" | "broadcast" | "agent-sync";
+  from: string;
+  to?: string;
+  topic?: string;
+  payload: string;
+  timestamp: number;
+}
+
+export interface MeshConfig {
+  listenAddrs?: string[];
+  discovery?: "mdns" | "bootstrap" | "dht";
+  bootstrapList?: string[];
+  meshTopic?: string;
+  enableAgentSync?: boolean;
+  enableWebSocket?: boolean;
+  peerIdPath?: string;
+}
+
+export interface MeshNetwork {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  sendToPeer(peerId: string, message: string): Promise<void>;
+  onMessage(handler: (msg: P2PMessage) => void): () => void;
+  publishToTopic(topic: string, message: string): Promise<void>;
+  subscribeToTopic(topic: string, handler: (msg: string) => void): Promise<void>;
+  getLocalPeerId(): string;
+  getConnectedPeers(): string[];
+}
+
+export type MeshAccount = {
+  accountId: string;
+  configured: boolean;
+  enabled: boolean;
+};