libp2p-mesh 2026.6.11 → 2026.6.13

package/README.md

@@ -10,6 +10,7 @@ P2P mesh network plugin for OpenClaw. Enables direct peer-to-peer communication
 - **Bootstrap Mode** — Optional static bootstrap peer list for non-LAN scenarios
 - **WebSocket Transport** — Optional WebSocket support for NAT/firewall-friendly connections
 - **NAT Traversal** — Built-in AutoNAT + UPnP + Circuit Relay v2 + DCUtR for peers behind home routers / firewalls
+- **User Public Attributes** — Announce public tags and structured profile attributes so agents can dry-run and send to locally discovered instances by attribute
 
 ## Requirements
 
@@ -443,6 +444,129 @@ The sender reports success only after the remote OpenClaw instance forwards the
 
 Tools are not configured in `openclaw.json`; they are registered automatically by the plugin through `api.registerTool()`.
 
+### User public attributes
+
+`libp2p-mesh` can announce user public attributes with instance route announcements. These attributes help agents find matching OpenClaw instances after those instances have already been discovered through the mesh.
+
+There are two sources:
+
+- `USER.md` tags are extracted read-only at gateway startup. The plugin never edits `USER.md`.
+- `user-profile.json` stores manually managed structured attributes such as group, project, role, skill, or a custom key.
+
+Run the profile wizard to manage structured attributes:
+
+```bash
+openclaw libp2p-mesh profile
+```
+
+The wizard previews read-only `USER.md` tags and lets you add, edit, or remove only structured profile attributes. Tags extracted from `USER.md` are not written to `user-profile.json`; they are merged in memory with profile attributes and broadcast only in instance announce messages.
+
+The default profile path is:
+
+```text
+~/.openclaw/libp2p/user-profile.json
+```
+
+When `OPENCLAW_STATE_DIR` is set:
+
+```text
+$OPENCLAW_STATE_DIR/libp2p/user-profile.json
+```
+
+Example `user-profile.json`:
+
+```json
+{
+  "version": 1,
+  "updatedAt": 1782180000000,
+  "attributes": [
+    {
+      "kind": "structured",
+      "key": "project",
+      "value": "openclaw",
+      "label": "project: openclaw",
+      "source": "profile"
+    },
+    {
+      "kind": "structured",
+      "key": "role",
+      "value": "maintainer",
+      "label": "role: maintainer",
+      "source": "profile"
+    }
+  ]
+}
+```
+
+Remote attributes are cached in plugin-managed instance state under `instance-peer.json.userPublicAttributes`:
+
+```json
+{
+  "version": 1,
+  "updatedAt": 1782180000000,
+  "instances": {
+    "alice-mac@AQIDBAUGBweI.7a3f9e2b": {
+      "instanceId": "alice-mac@AQIDBAUGBweI.7a3f9e2b",
+      "peerId": "12D3KooW...",
+      "instanceName": "alice-mac",
+      "multiaddrs": ["/ip4/192.168.1.23/tcp/4001"],
+      "userPublicAttributes": [
+        {
+          "kind": "tag",
+          "value": "libp2p",
+          "label": "libp2p",
+          "source": "USER.md"
+        },
+        {
+          "kind": "structured",
+          "key": "project",
+          "value": "openclaw",
+          "label": "project: openclaw",
+          "source": "profile"
+        }
+      ],
+      "lastSeenAt": 1782180000000,
+      "lastAnnouncedAt": 1782180000000,
+      "source": "announce"
+    }
+  }
+}
+```
+
+Use `p2p_send_user_attribute_message` for attribute-based group messages. Always dry-run first, review the matched instances with the user, then send only after confirmation:
+
+```text
+p2p_send_user_attribute_message({
+  "match": { "kind": "structured", "key": "project", "value": "openclaw" },
+  "message": "今晚同步一下进展",
+  "dryRun": true
+})
+```
+
+After confirming the dry-run targets:
+
+```text
+p2p_send_user_attribute_message({
+  "match": { "kind": "structured", "key": "project", "value": "openclaw" },
+  "message": "今晚同步一下进展",
+  "dryRun": false
+})
+```
+
+Tag matches use only the tag value:
+
+```text
+p2p_send_user_attribute_message({
+  "match": { "kind": "tag", "value": "libp2p" },
+  "message": "libp2p 方向有个问题想确认",
+  "dryRun": true
+})
+```
+
+The first version matches only instances already present in the local `instance-peer.json` discovery cache. It does not search the whole network or ask disconnected peers for more users.
+
+Privacy boundary: public attributes are broadcast with instance announce messages to peers your gateway connects to. Do not put private, sensitive, or access-controlled information in `USER.md` tags or `user-profile.json` structured attributes.
+
 ## Troubleshooting
 
 ### Peers do not discover each other

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

@@ -1,4 +1,13 @@
-import type { DeliveryTargetResult, InstanceRouter, MeshNetwork } from "./types.js";
+import type { DeliveryTargetResult, InstanceRouter, MeshNetwork, UserPublicAttribute } from "./types.js";
+type SendUserAttributeToolParams = {
+    match?: {
+        kind?: unknown;
+        key?: unknown;
+        value?: unknown;
+    };
+    message?: unknown;
+    dryRun?: unknown;
+};
 export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter): ({
     name: string;
     label: string;
@@ -16,6 +25,8 @@ export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter
             };
             topic?: undefined;
             instanceId?: undefined;
+            match?: undefined;
+            dryRun?: undefined;
         };
         required: string[];
     };
@@ -62,6 +73,8 @@ export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter
             };
             peerId?: undefined;
             instanceId?: undefined;
+            match?: undefined;
+            dryRun?: undefined;
         };
         required: string[];
     };
@@ -102,6 +115,8 @@ export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter
             message?: undefined;
             topic?: undefined;
             instanceId?: undefined;
+            match?: undefined;
+            dryRun?: undefined;
         };
         required?: undefined;
     };
@@ -141,6 +156,8 @@ export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter
             message?: undefined;
             topic?: undefined;
             instanceId?: undefined;
+            match?: undefined;
+            dryRun?: undefined;
         };
         required?: undefined;
     };
@@ -189,6 +206,8 @@ export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter
             message?: undefined;
             topic?: undefined;
             instanceId?: undefined;
+            match?: undefined;
+            dryRun?: undefined;
         };
         required?: undefined;
     };
@@ -230,6 +249,8 @@ export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter
             message?: undefined;
             topic?: undefined;
             instanceId?: undefined;
+            match?: undefined;
+            dryRun?: undefined;
         };
         required?: undefined;
     };
@@ -258,6 +279,7 @@ export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter
                 instanceName?: string;
                 multiaddrs: string[];
                 pubkey?: string;
+                userPublicAttributes?: UserPublicAttribute[];
                 lastSeenAt: number;
                 lastAnnouncedAt: number;
                 source: "announce";
@@ -294,6 +316,8 @@ export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter
             peerId?: undefined;
             message?: undefined;
             topic?: undefined;
+            match?: undefined;
+            dryRun?: undefined;
         };
         required: string[];
     };
@@ -369,6 +393,8 @@ export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter
             };
             peerId?: undefined;
             topic?: undefined;
+            match?: undefined;
+            dryRun?: undefined;
         };
         required: string[];
     };
@@ -430,4 +456,97 @@ export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter
         };
         isError?: undefined;
     }>;
+} | {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: {
+            match: {
+                type: "object";
+                description: string;
+                oneOf: ({
+                    type: "object";
+                    additionalProperties: boolean;
+                    properties: {
+                        kind: {
+                            const: "tag";
+                        };
+                        value: {
+                            type: "string";
+                            description: string;
+                        };
+                        key?: undefined;
+                    };
+                    required: string[];
+                } | {
+                    type: "object";
+                    additionalProperties: boolean;
+                    properties: {
+                        kind: {
+                            const: "structured";
+                        };
+                        key: {
+                            type: "string";
+                            description: string;
+                        };
+                        value: {
+                            type: "string";
+                            description: string;
+                        };
+                    };
+                    required: string[];
+                })[];
+            };
+            message: {
+                type: "string";
+                description: string;
+            };
+            dryRun: {
+                type: "boolean";
+                description: string;
+            };
+            peerId?: undefined;
+            topic?: undefined;
+            instanceId?: undefined;
+        };
+        required: string[];
+    };
+    execute(_toolCallId: string, params: SendUserAttributeToolParams): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {
+            initialized: boolean;
+            error?: undefined;
+        };
+        isError: boolean;
+    } | {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {
+            error: string;
+            initialized?: undefined;
+        };
+        isError: boolean;
+    } | {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: import("./types.js").UserAttributeMessageResult;
+        isError?: undefined;
+    } | {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: import("./types.js").UserAttributeMessageResult;
+        isError: boolean | undefined;
+    }>;
 })[];
+export {};

package/dist/src/agent-tools.js

@@ -12,6 +12,49 @@ function formatDeliveryResults(instanceId, delivered, results) {
     });
     return [heading, ...lines].join("\n");
 }
+function attributeLabel(attribute) {
+    if (attribute.kind === "tag") {
+        return `tag:${attribute.value}`;
+    }
+    return `${attribute.key}:${attribute.value}`;
+}
+function instanceTargetLabel(target) {
+    const name = target.instanceName ? ` (${target.instanceName})` : "";
+    return `${target.instanceId}${name} -> ${target.peerId}`;
+}
+function formatUserAttributeTargets(targets) {
+    return targets.map((target) => `${instanceTargetLabel(target)} [${attributeLabel(target.matchedAttribute)}]`);
+}
+function formatUserAttributeResults(results) {
+    return results.map((result) => {
+        let status = "已送达";
+        if (!result.sent) {
+            status = `发送失败：${result.error ?? "unknown error"}`;
+        }
+        else if (!result.delivered) {
+            status = `投递失败：${result.error ?? "unknown error"}`;
+        }
+        return `${instanceTargetLabel(result)}：${status}`;
+    });
+}
+function normalizeUserAttributeMatch(params) {
+    const match = params.match;
+    if (!match || typeof match !== "object") {
+        return "match is required.";
+    }
+    if (match.kind === "tag") {
+        const value = typeof match.value === "string" ? match.value.trim() : "";
+        return value ? { kind: "tag", value } : "match.value is required for tag matches.";
+    }
+    if (match.kind === "structured") {
+        const key = typeof match.key === "string" ? match.key.trim() : "";
+        const value = typeof match.value === "string" ? match.value.trim() : "";
+        return key && value
+            ? { kind: "structured", key, value }
+            : "match.key and match.value are required for structured matches.";
+    }
+    return 'match.kind must be "tag" or "structured".';
+}
 export function buildP2PTools(mesh, router) {
     return [
         {
@@ -369,5 +412,115 @@ export function buildP2PTools(mesh, router) {
                 };
             },
         },
+        {
+            name: "p2p_send_user_attribute_message",
+            label: "P2P Send User Attribute Message",
+            description: "Send a user message to discovered OpenClaw instances matching a public user attribute. Always run a dry run with dryRun=true first and ask the user to confirm targets before group sending.",
+            parameters: {
+                type: "object",
+                properties: {
+                    match: {
+                        type: "object",
+                        description: 'User public attribute match. Use { "kind": "tag", "value": "..." } for USER.md tags or { "kind": "structured", "key": "...", "value": "..." } for profile attributes.',
+                        oneOf: [
+                            {
+                                type: "object",
+                                additionalProperties: false,
+                                properties: {
+                                    kind: { const: "tag" },
+                                    value: {
+                                        type: "string",
+                                        description: "Tag value to match.",
+                                    },
+                                },
+                                required: ["kind", "value"],
+                            },
+                            {
+                                type: "object",
+                                additionalProperties: false,
+                                properties: {
+                                    kind: { const: "structured" },
+                                    key: {
+                                        type: "string",
+                                        description: "Structured attribute key to match.",
+                                    },
+                                    value: {
+                                        type: "string",
+                                        description: "Structured attribute value to match.",
+                                    },
+                                },
+                                required: ["kind", "key", "value"],
+                            },
+                        ],
+                    },
+                    message: {
+                        type: "string",
+                        description: "Message content to send after dry-run target confirmation.",
+                    },
+                    dryRun: {
+                        type: "boolean",
+                        description: "Preview matching instances without sending. Run this before group sending.",
+                    },
+                },
+                required: ["match", "message"],
+            },
+            async execute(_toolCallId, params) {
+                if (!router) {
+                    return {
+                        content: [{ type: "text", text: "Instance router is not initialized." }],
+                        details: { initialized: false },
+                        isError: true,
+                    };
+                }
+                const match = normalizeUserAttributeMatch(params);
+                const message = typeof params.message === "string" ? params.message.trim() : "";
+                if (typeof match === "string" || !message) {
+                    const error = typeof match === "string" ? match : "message is required.";
+                    return {
+                        content: [{ type: "text", text: error }],
+                        details: { error },
+                        isError: true,
+                    };
+                }
+                const dryRun = params.dryRun === true;
+                const result = await router.sendUserAttributeMessage(match, message, { dryRun });
+                if (result.error) {
+                    return {
+                        content: [{ type: "text", text: result.error }],
+                        details: result,
+                        isError: true,
+                    };
+                }
+                if (dryRun) {
+                    const targetLines = formatUserAttributeTargets(result.targets ?? []);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: [
+                                    `Dry run matched ${result.matched} instance(s). No message was sent.`,
+                                    ...targetLines,
+                                ].join("\n"),
+                            },
+                        ],
+                        details: result,
+                    };
+                }
+                const resultLines = formatUserAttributeResults(result.results ?? []);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                `Matched ${result.matched} instance(s); sent ${result.sent}; delivered ${result.delivered}; failed ${result.failed}.`,
+                                ...resultLines,
+                            ].join("\n"),
+                        },
+                    ],
+                    details: result,
+                    isError: result.failed > 0 ? true : undefined,
+                };
+            },
+        },
     ];
 }

package/dist/src/instance-peer-store.js

@@ -1,6 +1,7 @@
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
+import { normalizeUserPublicAttribute } from "./user-attributes.js";
 export function resolveInstancePeerPath(customPath) {
     if (customPath)
         return customPath;
@@ -22,25 +23,56 @@ function sameStringArray(a = [], b = []) {
         return false;
     return a.every((value, index) => value === b[index]);
 }
+function normalizeUserPublicAttributes(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .map((attribute) => normalizeUserPublicAttribute(attribute))
+        .filter((attribute) => attribute !== undefined);
+}
+function sameUserPublicAttributes(a = [], b = []) {
+    if (a.length !== b.length)
+        return false;
+    return a.every((attribute, index) => {
+        const other = b[index];
+        return JSON.stringify(attribute) === JSON.stringify(other);
+    });
+}
 function sameRecord(record, payload) {
     if (!record)
         return false;
+    const recordAttributes = normalizeUserPublicAttributes(record.userPublicAttributes);
+    const payloadAttributes = normalizeUserPublicAttributes(payload.userPublicAttributes);
     return (record.peerId === payload.peerId &&
         record.instanceName === payload.instanceName &&
         record.pubkey === payload.pubkey &&
         sameStringArray(record.multiaddrs, payload.multiaddrs) &&
+        sameUserPublicAttributes(recordAttributes, payloadAttributes) &&
         record.lastAnnouncedAt === payload.announcedAt);
 }
+function normalizeRecord(value) {
+    return {
+        ...value,
+        userPublicAttributes: normalizeUserPublicAttributes(value.userPublicAttributes),
+    };
+}
 function normalizeTable(value) {
     const candidate = value && typeof value === "object" ? value : {};
     const table = candidate;
     const instances = table.instances && typeof table.instances === "object" && !Array.isArray(table.instances)
         ? table.instances
         : {};
+    const normalizedInstances = {};
+    for (const [instanceId, record] of Object.entries(instances)) {
+        if (record && typeof record === "object") {
+            normalizedInstances[instanceId] = normalizeRecord(record);
+        }
+    }
     return {
         version: 1,
         updatedAt: typeof table.updatedAt === "number" ? table.updatedAt : Date.now(),
-        instances: instances,
+        instances: normalizedInstances,
     };
 }
 export function createInstancePeerStore(options) {
@@ -103,6 +135,7 @@ export function createInstancePeerStore(options) {
             return runMutation(async () => {
                 const table = await load();
                 const existing = table.instances[payload.instanceId];
+                const userPublicAttributes = normalizeUserPublicAttributes(payload.userPublicAttributes);
                 const changed = !sameRecord(existing, payload);
                 const record = {
                     instanceId: payload.instanceId,
@@ -110,6 +143,7 @@ export function createInstancePeerStore(options) {
                     instanceName: payload.instanceName,
                     pubkey: payload.pubkey,
                     multiaddrs: payload.multiaddrs,
+                    userPublicAttributes,
                     lastAnnouncedAt: payload.announcedAt,
                     lastSeenAt: Date.now(),
                     source: "announce",

package/dist/src/instance-router.d.ts

@@ -1,14 +1,8 @@
-import type { InboundDeliveryAdapter, InstancePeerStore, InstanceRouter, MeshConfig, MeshNetwork } from "./types.js";
+import type { InstanceRouter, InstanceRouterOptions } from "./types.js";
 export type RouterLogger = {
     info?: (message: string) => void;
     debug?: (message: string) => void;
     warn?: (message: string) => void;
     error?: (message: string) => void;
 };
-export declare function createInstanceRouter(options: {
-    mesh: MeshNetwork;
-    store: InstancePeerStore;
-    delivery: InboundDeliveryAdapter;
-    config?: MeshConfig;
-    logger?: RouterLogger;
-}): InstanceRouter;
+export declare function createInstanceRouter(options: InstanceRouterOptions): InstanceRouter;