libp2p-mesh 2026.6.12 → 2026.6.14

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
 
@@ -224,11 +225,34 @@ If `inboundTargets` is an empty array, inbound delivery is disabled. If `inbound
 | `relayList` | `string[]` | `[]` | Multiaddrs of relays to reserve a slot on |
 | `discoverRelays` | `number` | `0` | Auto-discover this many relays via content routing |
 | `announceAddrs` | `string[]` | `[]` | Extra multiaddrs to announce on top of auto-detected ones |
+| `announceLogDetail` | `"off" \| "summary" \| "payload"` | `"summary"` | Controls instance announce logging. `summary` logs peer, instance, address count, and attribute count; `payload` also logs the full announce JSON; `off` disables only the new announce summary/payload logs and keeps legacy/basic info logs. |
 | `inboundChannel` | `string` | `undefined` | OpenClaw channel used to display inbound P2P user messages, for example `"feishu"` |
 | `inboundTarget` | `string` | `undefined` | OpenClaw channel target for inbound P2P messages, for example `user:ou_xxx` or `chat:oc_xxx` |
 | `inboundTargets` | `array` | `undefined` | Optional list of receiver-owned channel targets for inbound P2P user messages. When present, it overrides `inboundChannel`/`inboundTarget`; an empty array disables inbound delivery. |
 | `deliveryAckTimeoutMs` | `number` | `15000` | Timeout for waiting on remote channel delivery ACKs |
 
+### Announce Startup and Logging
+
+During gateway startup, `libp2p-mesh` registers the instance router handlers and direct/broadcast inbound handlers before starting the mesh node. This makes early `instance-announce` messages observable as soon as peers connect, instead of waiting until after mesh startup has already completed.
+
+Instance announce logs are controlled by `plugins.entries["libp2p-mesh"].config.announceLogDetail`:
+
+- `summary` is the default. It logs send/receive direction, peer ID, instance ID, multiaddr count, and public attribute count. It does not print the full announce JSON.
+- `off` disables the new announce summary and payload logs. It still keeps legacy/basic info logs such as sent announce lines and instance mapping updates, along with warnings and errors.
+- `payload` logs the same summary plus the full announce JSON at debug level.
+
+Use the debug command to inspect or change this value:
+
+```bash
+openclaw libp2p-mesh debug
+```
+
+Full payload logging is intended for short-lived troubleshooting only. Announce payloads can include `userPublicAttributes`, peer multiaddrs, the instance pubkey, and instance identity fields. After changing the setting, restart the gateway for the new logging level to take effect:
+
+```bash
+openclaw gateway restart
+```
+
 ## NAT Traversal
 
 When both peers have a routable address (same LAN, public IPs, or working port-forwarding) no extra setup is needed. The defaults above kick in automatically:
@@ -443,6 +467,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
@@ -492,6 +639,20 @@ Peer connection and disconnection are logged at `info` level:
 
 If these lines are missing, confirm the gateway is running with normal info logs enabled and that both instances are on the same mDNS, bootstrap, or relay network.
 
+### Instance announce routes are missing between two machines
+
+If peers connect but sending by OpenClaw instance ID fails or `instance-peer.json` is not updated, first confirm both gateways were restarted after the latest config change. On startup, the gateway now attaches the instance router plus inbound message handlers before starting the mesh, so early announces should be handled once the peer connection appears.
+
+For a short debug session on both computers:
+
+1. Run `openclaw libp2p-mesh debug`.
+2. Set `announceLogDetail` to `payload` and confirm the privacy warning.
+3. Restart both gateways with `openclaw gateway restart`.
+4. Watch for summary lines and debug lines containing full announce payload JSON.
+5. Return to `summary` or `off` with `openclaw libp2p-mesh debug`, then restart again.
+
+Full payload logs may expose `userPublicAttributes`, multiaddrs, pubkey, and instance identity, so avoid sharing these logs outside the debugging context.
+
 ## Architecture
 
 ```

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/debug-cli.d.ts

@@ -0,0 +1,21 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import type { OpenClawPluginCliContext } from "openclaw/plugin-sdk/plugin-runtime";
+import type { SetupPrompter } from "./setup-wizard.js";
+import type { AnnounceLogDetail } from "./types.js";
+type CliRootCommand = {
+    command(name: string): {
+        description(text: string): {
+            action(handler: () => Promise<void>): void;
+        };
+    };
+};
+export type DebugConfigWriter = {
+    saveAnnounceLogDetail(detail: AnnounceLogDetail): Promise<void>;
+};
+export type DebugCliDeps = {
+    createPrompter?: (ctx: OpenClawPluginCliContext) => SetupPrompter;
+    createWriter?: (api: OpenClawPluginApi) => DebugConfigWriter;
+};
+export declare function registerLibp2pMeshDebugCli(api: OpenClawPluginApi, deps?: DebugCliDeps): void;
+export declare function registerLibp2pMeshDebugCommand(root: CliRootCommand, api: OpenClawPluginApi, ctx: OpenClawPluginCliContext, deps?: DebugCliDeps): void;
+export {};

package/dist/src/debug-cli.js

@@ -0,0 +1,54 @@
+import { createReadlinePrompter, LIBP2P_MESH_CLI_REGISTRATION, } from "./setup-cli.js";
+import { applyAnnounceLogDetail, getAnnounceLogDetail, } from "./setup-config.js";
+import { runDebugWizard } from "./debug-wizard.js";
+const DEBUG_CLI_AFTER_WRITE = {
+    mode: "none",
+    reason: "libp2p-mesh debug config updated; restart manually to apply gateway changes.",
+};
+export function registerLibp2pMeshDebugCli(api, deps = {}) {
+    api.registerCli((ctx) => {
+        const root = ctx.program
+            .command("libp2p-mesh")
+            .description("Configure libp2p-mesh plugin.");
+        registerLibp2pMeshDebugCommand(root, api, ctx, deps);
+    }, LIBP2P_MESH_CLI_REGISTRATION);
+}
+export function registerLibp2pMeshDebugCommand(root, api, ctx, deps = {}) {
+    root
+        .command("debug")
+        .description("Manage libp2p-mesh debug logging config.")
+        .action(async () => {
+        const prompter = (deps.createPrompter?.(ctx) ?? createReadlinePrompter());
+        const writer = deps.createWriter?.(api) ?? createOpenClawDebugConfigWriter(api);
+        try {
+            const result = await runDebugWizard({
+                prompter,
+                current: getAnnounceLogDetail(ctx.config),
+                writer,
+            });
+            prompter.print(result.message);
+        }
+        finally {
+            prompter.close?.();
+        }
+    });
+}
+function createOpenClawDebugConfigWriter(api) {
+    return {
+        async saveAnnounceLogDetail(detail) {
+            await api.runtime.config.mutateConfigFile({
+                afterWrite: DEBUG_CLI_AFTER_WRITE,
+                mutate(draft) {
+                    const nextConfig = applyAnnounceLogDetail(draft, detail);
+                    replaceConfig(draft, nextConfig);
+                },
+            });
+        },
+    };
+}
+function replaceConfig(draft, nextConfig) {
+    for (const key of Object.keys(draft)) {
+        delete draft[key];
+    }
+    Object.assign(draft, structuredClone(nextConfig));
+}

package/dist/src/debug-wizard.d.ts

@@ -0,0 +1,19 @@
+import { type SetupPrompter } from "./setup-wizard.js";
+import type { AnnounceLogDetail } from "./types.js";
+export type DebugPromptChoice = AnnounceLogDetail | "cancel";
+export type RunDebugWizardOptions = {
+    prompter: SetupPrompter;
+    current: AnnounceLogDetail;
+    writer: {
+        saveAnnounceLogDetail(detail: AnnounceLogDetail): Promise<void>;
+    };
+};
+export type DebugWizardResult = {
+    status: "saved";
+    announceLogDetail: AnnounceLogDetail;
+    message: string;
+} | {
+    status: "cancelled";
+    message: string;
+};
+export declare function runDebugWizard(options: RunDebugWizardOptions): Promise<DebugWizardResult>;

package/dist/src/debug-wizard.js

@@ -0,0 +1,41 @@
+import { SetupCancelledError } from "./setup-wizard.js";
+const CANCELLED_MESSAGE = "Debug configuration cancelled. No changes were written.";
+const SAVED_MESSAGE = "Debug config updated.\n\nRestart the gateway to apply changes:\nopenclaw gateway restart";
+export async function runDebugWizard(options) {
+    try {
+        options.prompter.print(`Current announceLogDetail: ${options.current}`);
+        const selected = await options.prompter.select("Set announceLogDetail:", [
+            { label: "summary: log peer, instance, address and attribute counts", value: "summary" },
+            { label: "off: disable announce summary/payload logs", value: "off" },
+            { label: "payload: log full announce JSON", value: "payload" },
+            { label: "Cancel", value: "cancel" },
+        ]);
+        if (selected === "cancel") {
+            return cancelledResult();
+        }
+        if (selected === "payload") {
+            const confirmed = await options.prompter.confirm("Full announce payload logs may include userPublicAttributes, multiaddrs, pubkey and instance identity. Enable payload logs?", false);
+            if (!confirmed) {
+                return cancelledResult();
+            }
+        }
+        await options.writer.saveAnnounceLogDetail(selected);
+        return {
+            status: "saved",
+            announceLogDetail: selected,
+            message: SAVED_MESSAGE,
+        };
+    }
+    catch (error) {
+        if (error instanceof SetupCancelledError) {
+            return cancelledResult();
+        }
+        throw error;
+    }
+}
+function cancelledResult() {
+    return {
+        status: "cancelled",
+        message: CANCELLED_MESSAGE,
+    };
+}