libp2p-mesh 2026.6.12 → 2026.6.13

package/dist/src/instance-router.js

@@ -1,3 +1,4 @@
+import { matchesUserAttribute, mergeUserPublicAttributes } from "./user-attributes.js";
 const MAX_DELIVERY_CACHE_ENTRIES = 1000;
 function parsePayload(msg) {
     try {
@@ -13,6 +14,12 @@ function isNonEmptyString(value) {
 function summarizeError(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function describeAttributeMatch(match) {
+    if (match.kind === "tag") {
+        return `tag ${match.value}`;
+    }
+    return `structured attribute ${match.key}=${match.value}`;
+}
 function displayTargetId(target) {
     const id = typeof target.id === "string" ? target.id.trim() : "";
     return id && id.length > 0 ? id : undefined;
@@ -86,7 +93,20 @@ export function createInstanceRouter(options) {
         }
         return identity.id;
     }
-    function buildAnnouncePayload() {
+    async function loadUserPublicAttributes() {
+        const [userMdTags, profileAttributes] = await Promise.all([
+            options.userAttributeSource?.loadTags().catch((error) => {
+                logger?.warn?.(`[libp2p-mesh] Failed to load USER.md public attributes: ${summarizeError(error)}`);
+                return [];
+            }) ?? Promise.resolve([]),
+            options.userProfileStore?.listAttributes().catch((error) => {
+                logger?.warn?.(`[libp2p-mesh] Failed to load profile public attributes: ${summarizeError(error)}`);
+                return [];
+            }) ?? Promise.resolve([]),
+        ]);
+        return mergeUserPublicAttributes(userMdTags, profileAttributes);
+    }
+    async function buildAnnouncePayload() {
         const identity = mesh.getInstanceIdentity();
         if (!identity) {
             throw new Error("Local instance identity is not initialized");
@@ -97,6 +117,7 @@ export function createInstanceRouter(options) {
             instanceName: identity.name,
             multiaddrs: mesh.getMultiaddrs(),
             pubkey: identity.pubkey,
+            userPublicAttributes: await loadUserPublicAttributes(),
             announcedAt: Date.now(),
         };
     }
@@ -104,7 +125,7 @@ export function createInstanceRouter(options) {
         if (!isNonEmptyString(peerId) || peerId === mesh.getLocalPeerId()) {
             return;
         }
-        const payload = buildAnnouncePayload();
+        const payload = await buildAnnouncePayload();
         await mesh.sendStructuredMessage(peerId, {
             id: crypto.randomUUID(),
             type: "instance-announce",
@@ -413,6 +434,76 @@ export function createInstanceRouter(options) {
             error: ack.error,
         };
     }
+    async function resolveUserAttributeTargets(match) {
+        const records = await store.list();
+        const targets = [];
+        for (const record of records) {
+            const matchedAttribute = record.userPublicAttributes?.find((attribute) => matchesUserAttribute(attribute, match));
+            if (!matchedAttribute) {
+                continue;
+            }
+            targets.push({
+                instanceId: record.instanceId,
+                instanceName: record.instanceName,
+                peerId: record.peerId,
+                matchedAttribute,
+            });
+        }
+        return targets;
+    }
+    async function sendUserAttributeMessage(match, message, sendOptions = {}) {
+        const targets = await resolveUserAttributeTargets(match);
+        if (targets.length === 0) {
+            return {
+                matched: 0,
+                sent: 0,
+                delivered: 0,
+                failed: 0,
+                error: `No discovered instances match ${describeAttributeMatch(match)}.`,
+            };
+        }
+        if (sendOptions.dryRun === true) {
+            return {
+                matched: targets.length,
+                sent: 0,
+                delivered: 0,
+                failed: 0,
+                targets,
+            };
+        }
+        const results = [];
+        for (const target of targets) {
+            try {
+                const result = await sendInstanceMessage(target.instanceId, message);
+                const targetResult = {
+                    ...target,
+                    sent: result.sent,
+                    delivered: result.delivered,
+                };
+                if (result.error) {
+                    results.push({ ...targetResult, error: result.error });
+                }
+                else {
+                    results.push(targetResult);
+                }
+            }
+            catch (error) {
+                results.push({
+                    ...target,
+                    sent: false,
+                    delivered: false,
+                    error: summarizeError(error),
+                });
+            }
+        }
+        return {
+            matched: targets.length,
+            sent: results.filter((result) => result.sent).length,
+            delivered: results.filter((result) => result.delivered).length,
+            failed: results.filter((result) => !result.delivered).length,
+            results,
+        };
+    }
     return {
         start,
         stop,
@@ -421,5 +512,6 @@ export function createInstanceRouter(options) {
         listInstances,
         resolveInstance,
         sendInstanceMessage,
+        sendUserAttributeMessage,
     };
 }

package/dist/src/plugin.js

@@ -4,10 +4,12 @@ import { createOpenClawRuntimeInboundDelivery } from "./inbound-delivery.js";
 import { createInstancePeerStore } from "./instance-peer-store.js";
 import { createInstanceRouter } from "./instance-router.js";
 import { createMeshNetwork } from "./mesh.js";
+import { createUserMdAttributeSource } from "./user-md-attributes.js";
+import { createUserProfileStore } from "./user-profile-store.js";
 import { buildP2PTools } from "./agent-tools.js";
-import { registerLibp2pMeshSetupCli } from "./setup-cli.js";
+import { registerLibp2pMeshCli } from "./profile-cli.js";
 export function registerLibp2pMesh(api) {
-    registerLibp2pMeshSetupCli(api);
+    registerLibp2pMeshCli(api);
     const config = api.pluginConfig;
     let unsubscribeInbound;
     let serviceStarted = false;
@@ -16,6 +18,8 @@ export function registerLibp2pMesh(api) {
         logger: api.logger,
     });
     const store = createInstancePeerStore({ logger: api.logger });
+    const userAttributeSource = createUserMdAttributeSource({ logger: api.logger });
+    const userProfileStore = createUserProfileStore({ logger: api.logger });
     const delivery = createOpenClawRuntimeInboundDelivery({
         config: api.config,
         loadAdapter: async (channelId) => {
@@ -34,6 +38,8 @@ export function registerLibp2pMesh(api) {
         delivery,
         config,
         logger: api.logger,
+        userAttributeSource,
+        userProfileStore,
     });
     const channel = createLibp2pMeshChannel(mesh);
     // 1. Register Service (manages libp2p node lifecycle)

package/dist/src/profile-cli.d.ts

@@ -0,0 +1,27 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import type { OpenClawPluginCliContext } from "openclaw/plugin-sdk/plugin-runtime";
+import { type SetupCliDeps } from "./setup-cli.js";
+import { type UserProfileStore } from "./user-profile-store.js";
+import type { SetupPrompter } from "./setup-wizard.js";
+type CliRootCommand = {
+    command(name: string): {
+        description(text: string): {
+            action(handler: () => Promise<void>): void;
+        };
+    };
+};
+export type ProfileCliDeps = {
+    createPrompter?: (ctx: OpenClawPluginCliContext) => SetupPrompter;
+    createProfileStore?: (api: OpenClawPluginApi) => Pick<UserProfileStore, "listAttributes" | "replaceAttributes">;
+    createUserMdAttributeSource?: (api: OpenClawPluginApi) => {
+        loadTags(): Promise<Awaited<ReturnType<UserProfileStore["listAttributes"]>>>;
+    };
+};
+export type Libp2pMeshCliDeps = {
+    setup?: SetupCliDeps;
+    profile?: ProfileCliDeps;
+};
+export declare function registerLibp2pMeshCli(api: OpenClawPluginApi, deps?: Libp2pMeshCliDeps): void;
+export declare function registerLibp2pMeshProfileCli(api: OpenClawPluginApi, deps?: ProfileCliDeps): void;
+export declare function registerLibp2pMeshProfileCommand(root: CliRootCommand, api: OpenClawPluginApi, ctx: OpenClawPluginCliContext, deps?: ProfileCliDeps): void;
+export {};

package/dist/src/profile-cli.js

@@ -0,0 +1,47 @@
+import { createReadlinePrompter, LIBP2P_MESH_CLI_REGISTRATION, registerLibp2pMeshSetupCommand, } from "./setup-cli.js";
+import { runProfileWizard } from "./profile-wizard.js";
+import { createUserMdAttributeSource } from "./user-md-attributes.js";
+import { createUserProfileStore } from "./user-profile-store.js";
+export function registerLibp2pMeshCli(api, deps = {}) {
+    api.registerCli((ctx) => {
+        const root = ctx.program
+            .command("libp2p-mesh")
+            .description("Configure libp2p-mesh plugin.");
+        registerLibp2pMeshSetupCommand(root, api, ctx, deps.setup);
+        registerLibp2pMeshProfileCommand(root, api, ctx, deps.profile);
+    }, LIBP2P_MESH_CLI_REGISTRATION);
+}
+export function registerLibp2pMeshProfileCli(api, deps = {}) {
+    api.registerCli((ctx) => {
+        const root = ctx.program
+            .command("libp2p-mesh")
+            .description("Configure libp2p-mesh plugin.");
+        registerLibp2pMeshProfileCommand(root, api, ctx, deps);
+    }, LIBP2P_MESH_CLI_REGISTRATION);
+}
+export function registerLibp2pMeshProfileCommand(root, api, ctx, deps = {}) {
+    root
+        .command("profile")
+        .description("Manage libp2p-mesh public profile attributes.")
+        .action(async () => {
+        const prompter = (deps.createPrompter?.(ctx) ?? createReadlinePrompter());
+        const profileStore = deps.createProfileStore?.(api) ?? createUserProfileStore({ logger: api.logger });
+        const userMdAttributeSource = deps.createUserMdAttributeSource?.(api) ?? createUserMdAttributeSource({ logger: api.logger });
+        try {
+            const result = await runProfileWizard({
+                prompter,
+                readOnlyTags: await userMdAttributeSource.loadTags(),
+                profileAttributes: await profileStore.listAttributes(),
+                writer: {
+                    async replaceAttributes(attributes) {
+                        await profileStore.replaceAttributes(attributes);
+                    },
+                },
+            });
+            prompter.print(result.message);
+        }
+        finally {
+            prompter.close?.();
+        }
+    });
+}

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

@@ -0,0 +1,20 @@
+import { type SetupPrompter } from "./setup-wizard.js";
+import type { UserPublicAttribute } from "./types.js";
+export type UserProfileWriter = {
+    replaceAttributes(attributes: UserPublicAttribute[]): Promise<void>;
+};
+export type RunProfileWizardOptions = {
+    prompter: SetupPrompter;
+    readOnlyTags: UserPublicAttribute[];
+    profileAttributes: UserPublicAttribute[];
+    writer: UserProfileWriter;
+};
+export type ProfileWizardResult = {
+    status: "saved";
+    attributes: UserPublicAttribute[];
+    message: string;
+} | {
+    status: "cancelled";
+    message: string;
+};
+export declare function runProfileWizard(options: RunProfileWizardOptions): Promise<ProfileWizardResult>;

package/dist/src/profile-wizard.js

@@ -0,0 +1,141 @@
+import { SetupCancelledError } from "./setup-wizard.js";
+import { mergeUserPublicAttributes, normalizeAttributeKey, normalizeUserPublicAttribute, } from "./user-attributes.js";
+const CANCELLED_MESSAGE = "Profile update cancelled. No changes were written.";
+const SAVED_MESSAGE = "Profile attributes saved.\n\nRestart the gateway to broadcast updated attributes.";
+export async function runProfileWizard(options) {
+    try {
+        const readOnlyTags = options.readOnlyTags
+            .map((attribute) => normalizeUserPublicAttribute(attribute))
+            .filter((attribute) => attribute?.kind === "tag");
+        let attributes = normalizeProfileAttributes(options.profileAttributes);
+        options.prompter.print(formatProfileOverview(readOnlyTags, attributes));
+        while (true) {
+            const action = await options.prompter.select("What do you want to do?", [
+                { label: "Add structured attribute", value: "add-attribute" },
+                { label: "Edit structured attribute", value: "edit-attribute" },
+                { label: "Remove structured attribute", value: "remove-attribute" },
+                { label: "Preview and finish", value: "preview-finish" },
+                { label: "Cancel", value: "cancel" },
+            ]);
+            switch (action) {
+                case "add-attribute":
+                    attributes = mergeUserPublicAttributes([], [...attributes, await promptForAttribute(options.prompter)]);
+                    options.prompter.print(formatProfileOverview(readOnlyTags, attributes));
+                    break;
+                case "edit-attribute":
+                    attributes = await promptForAttributeEdit(options.prompter, attributes);
+                    options.prompter.print(formatProfileOverview(readOnlyTags, attributes));
+                    break;
+                case "remove-attribute":
+                    attributes = await promptForAttributeRemoval(options.prompter, attributes);
+                    options.prompter.print(formatProfileOverview(readOnlyTags, attributes));
+                    break;
+                case "preview-finish":
+                    options.prompter.print(formatProfilePreview(readOnlyTags, attributes));
+                    if (!(await options.prompter.confirm("Save profile attributes?", true))) {
+                        return cancelledResult();
+                    }
+                    await options.writer.replaceAttributes(attributes);
+                    return {
+                        status: "saved",
+                        attributes,
+                        message: SAVED_MESSAGE,
+                    };
+                case "cancel":
+                    return cancelledResult();
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof SetupCancelledError) {
+            return cancelledResult();
+        }
+        throw error;
+    }
+}
+function normalizeProfileAttributes(attributes) {
+    return mergeUserPublicAttributes([], attributes).filter((attribute) => attribute.kind === "structured");
+}
+async function promptForAttribute(prompter) {
+    const category = await prompter.select("Attribute category", [
+        { label: "Group", value: "group" },
+        { label: "Project", value: "project" },
+        { label: "Role", value: "role" },
+        { label: "Skill", value: "skill" },
+        { label: "Custom key", value: "custom" },
+    ]);
+    const key = category === "custom"
+        ? normalizeAttributeKey(await prompter.input("Custom key", { required: true }))
+        : category;
+    const value = await prompter.input("Attribute value", { required: true });
+    return {
+        kind: "structured",
+        key,
+        value: value.trim(),
+        label: `${key}: ${value.trim()}`,
+        source: "profile",
+    };
+}
+async function promptForAttributeEdit(prompter, attributes) {
+    if (attributes.length === 0) {
+        prompter.print("No structured profile attributes configured.");
+        return attributes;
+    }
+    const selectedIndex = await selectAttributeIndex(prompter, "Attribute to edit", attributes);
+    const nextAttribute = await promptForAttribute(prompter);
+    return mergeUserPublicAttributes([], attributes.map((attribute, index) => (index === selectedIndex ? nextAttribute : attribute))).filter((attribute) => attribute.kind === "structured");
+}
+async function promptForAttributeRemoval(prompter, attributes) {
+    if (attributes.length === 0) {
+        prompter.print("No structured profile attributes configured.");
+        return attributes;
+    }
+    const selectedIndex = await selectAttributeIndex(prompter, "Attribute to remove", attributes);
+    return attributes.filter((_attribute, index) => index !== selectedIndex);
+}
+async function selectAttributeIndex(prompter, message, attributes) {
+    const selectedKey = await prompter.select(message, attributes.map((attribute, index) => ({
+        label: formatAttribute(attribute),
+        value: `attribute-index-${index}`,
+    })));
+    const match = /^attribute-index-(\d+)$/.exec(selectedKey);
+    return match ? Number(match[1]) : -1;
+}
+function formatProfileOverview(readOnlyTags, attributes) {
+    return [
+        "Read-only USER.md tags:",
+        ...formatAttributeList(readOnlyTags),
+        "",
+        "Structured profile attributes:",
+        ...formatAttributeList(attributes),
+    ].join("\n");
+}
+function formatProfilePreview(readOnlyTags, attributes) {
+    return [
+        "Preview: public attributes",
+        "",
+        "Read-only USER.md tags:",
+        ...formatAttributeList(readOnlyTags),
+        "",
+        "Structured profile attributes to save:",
+        ...formatAttributeList(attributes),
+    ].join("\n");
+}
+function formatAttributeList(attributes) {
+    if (attributes.length === 0) {
+        return ["  none"];
+    }
+    return attributes.map((attribute, index) => `  ${index + 1}. ${formatAttribute(attribute)}`);
+}
+function formatAttribute(attribute) {
+    if (attribute.kind === "tag") {
+        return `${attribute.label} (USER.md tag, read-only)`;
+    }
+    return `${attribute.key}: ${attribute.value}`;
+}
+function cancelledResult() {
+    return {
+        status: "cancelled",
+        message: CANCELLED_MESSAGE,
+    };
+}

package/dist/src/setup-cli.d.ts

@@ -1,8 +1,27 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
 import type { OpenClawPluginCliContext } from "openclaw/plugin-sdk/plugin-runtime";
 import { type SetupConfigWriter, type SetupPrompter } from "./setup-wizard.js";
+export declare const LIBP2P_MESH_CLI_REGISTRATION: {
+    commands: string[];
+    descriptors: {
+        name: string;
+        description: string;
+        hasSubcommands: boolean;
+    }[];
+};
+export type ClosableSetupPrompter = SetupPrompter & {
+    close?: () => void;
+};
 export type SetupCliDeps = {
     createPrompter?: (ctx: OpenClawPluginCliContext) => SetupPrompter;
     createWriter?: (api: OpenClawPluginApi) => SetupConfigWriter;
 };
 export declare function registerLibp2pMeshSetupCli(api: OpenClawPluginApi, deps?: SetupCliDeps): void;
+export declare function registerLibp2pMeshSetupCommand(root: {
+    command(name: string): {
+        description(text: string): {
+            action(handler: () => Promise<void>): void;
+        };
+    };
+}, api: OpenClawPluginApi, ctx: OpenClawPluginCliContext, deps?: SetupCliDeps): void;
+export declare function createReadlinePrompter(): ClosableSetupPrompter;

package/dist/src/setup-cli.js

@@ -5,38 +5,42 @@ const SETUP_CLI_AFTER_WRITE = {
     mode: "none",
     reason: "libp2p-mesh setup completed; restart manually to apply gateway changes.",
 };
+export const LIBP2P_MESH_CLI_REGISTRATION = {
+    commands: ["libp2p-mesh"],
+    descriptors: [
+        {
+            name: "libp2p-mesh",
+            description: "Configure libp2p-mesh plugin.",
+            hasSubcommands: true,
+        },
+    ],
+};
 export function registerLibp2pMeshSetupCli(api, deps = {}) {
     api.registerCli((ctx) => {
         const root = ctx.program
             .command("libp2p-mesh")
             .description("Configure libp2p-mesh plugin.");
-        root
-            .command("setup")
-            .description("Run the libp2p-mesh setup wizard.")
-            .action(async () => {
-            const prompter = (deps.createPrompter?.(ctx) ?? createReadlinePrompter());
-            const writer = deps.createWriter?.(api) ?? createOpenClawConfigWriter(api);
-            try {
-                const result = await runSetupWizard({
-                    currentConfig: ctx.config,
-                    prompter,
-                    writer,
-                });
-                prompter.print(result.message);
-            }
-            finally {
-                prompter.close?.();
-            }
-        });
-    }, {
-        commands: ["libp2p-mesh"],
-        descriptors: [
-            {
-                name: "libp2p-mesh",
-                description: "Configure libp2p-mesh plugin.",
-                hasSubcommands: true,
-            },
-        ],
+        registerLibp2pMeshSetupCommand(root, api, ctx, deps);
+    }, LIBP2P_MESH_CLI_REGISTRATION);
+}
+export function registerLibp2pMeshSetupCommand(root, api, ctx, deps = {}) {
+    root
+        .command("setup")
+        .description("Run the libp2p-mesh setup wizard.")
+        .action(async () => {
+        const prompter = (deps.createPrompter?.(ctx) ?? createReadlinePrompter());
+        const writer = deps.createWriter?.(api) ?? createOpenClawConfigWriter(api);
+        try {
+            const result = await runSetupWizard({
+                currentConfig: ctx.config,
+                prompter,
+                writer,
+            });
+            prompter.print(result.message);
+        }
+        finally {
+            prompter.close?.();
+        }
     });
 }
 function createOpenClawConfigWriter(api) {
@@ -57,7 +61,7 @@ function replaceConfig(draft, nextConfig) {
     }
     Object.assign(draft, structuredClone(nextConfig));
 }
-function createReadlinePrompter() {
+export function createReadlinePrompter() {
     const readline = createInterface({ input, output });
     return {
         async confirm(message, defaultValue = false) {

package/dist/src/types.d.ts

@@ -38,6 +38,7 @@ export interface InstanceAnnouncePayload {
     instanceName?: string;
     multiaddrs: string[];
     pubkey?: string;
+    userPublicAttributes?: UserPublicAttribute[];
     announcedAt: number;
 }
 export interface UserMessagePayload {
@@ -72,12 +73,33 @@ export interface DeliveryAckPayload {
     deliveredAt: number;
     error?: string;
 }
+export type UserPublicAttribute = {
+    kind: "tag";
+    value: string;
+    label: string;
+    source: "USER.md";
+} | {
+    kind: "structured";
+    key: "group" | "project" | "role" | "skill" | "custom" | string;
+    value: string;
+    label: string;
+    source: "profile";
+};
+export type UserAttributeMatch = {
+    kind: "tag";
+    value: string;
+} | {
+    kind: "structured";
+    key: string;
+    value: string;
+};
 export interface InstancePeerRecord {
     instanceId: string;
     peerId: string;
     instanceName?: string;
     multiaddrs: string[];
     pubkey?: string;
+    userPublicAttributes?: UserPublicAttribute[];
     lastSeenAt: number;
     lastAnnouncedAt: number;
     source: "announce";
@@ -97,6 +119,26 @@ export interface InstancePeerStore {
         peerIdSharedBy: string[];
     }>;
 }
+export type UserAttributeMessageTarget = {
+    instanceId: string;
+    instanceName?: string;
+    peerId: string;
+    matchedAttribute: UserPublicAttribute;
+};
+export type UserAttributeMessageDeliveryResult = UserAttributeMessageTarget & {
+    sent: boolean;
+    delivered: boolean;
+    error?: string;
+};
+export type UserAttributeMessageResult = {
+    matched: number;
+    sent: number;
+    delivered: number;
+    failed: number;
+    targets?: UserAttributeMessageTarget[];
+    results?: UserAttributeMessageDeliveryResult[];
+    error?: string;
+};
 export interface InboundDeliveryRequest {
     channel: string;
     target: string;
@@ -119,6 +161,24 @@ export interface InboundDeliveryResult {
 export interface InboundDeliveryAdapter {
     deliver(request: InboundDeliveryRequest): Promise<InboundDeliveryResult>;
 }
+export type InstanceRouterOptions = {
+    mesh: MeshNetwork;
+    store: InstancePeerStore;
+    delivery: InboundDeliveryAdapter;
+    config?: MeshConfig;
+    logger?: {
+        info?: (message: string) => void;
+        debug?: (message: string) => void;
+        warn?: (message: string) => void;
+        error?: (message: string) => void;
+    };
+    userAttributeSource?: {
+        loadTags(): Promise<UserPublicAttribute[]>;
+    };
+    userProfileStore?: {
+        listAttributes(): Promise<UserPublicAttribute[]>;
+    };
+};
 export interface InstanceRouter {
     start(): Promise<void>;
     stop(): Promise<void>;
@@ -137,6 +197,9 @@ export interface InstanceRouter {
         deliveryResults?: DeliveryTargetResult[];
         error?: string;
     }>;
+    sendUserAttributeMessage(match: UserAttributeMatch, message: string, options?: {
+        dryRun?: boolean;
+    }): Promise<UserAttributeMessageResult>;
 }
 export interface MeshConfig {
     listenAddrs?: string[];

package/dist/src/user-attributes.d.ts

@@ -0,0 +1,6 @@
+import type { UserAttributeMatch, UserPublicAttribute } from "./types.js";
+export declare function normalizeAttributeValue(value: string): string;
+export declare function normalizeAttributeKey(key: string): string;
+export declare function normalizeUserPublicAttribute(value: unknown): UserPublicAttribute | undefined;
+export declare function mergeUserPublicAttributes(userMdTags: UserPublicAttribute[], profileAttributes: UserPublicAttribute[]): UserPublicAttribute[];
+export declare function matchesUserAttribute(attribute: UserPublicAttribute, match: UserAttributeMatch): boolean;