libp2p-mesh 2026.6.12 → 2026.6.13

package/src/agent-tools.ts

@@ -1,4 +1,12 @@
-import type { DeliveryTargetResult, InstanceRouter, MeshNetwork } from "./types.js";
+import type {
+  DeliveryTargetResult,
+  InstanceRouter,
+  MeshNetwork,
+  UserAttributeMatch,
+  UserAttributeMessageDeliveryResult,
+  UserAttributeMessageTarget,
+  UserPublicAttribute,
+} from "./types.js";
 
 function targetLabel(result: DeliveryTargetResult) {
   const name = result.id ?? `${result.channel}:${result.target}`;
@@ -20,6 +28,68 @@ function formatDeliveryResults(
   return [heading, ...lines].join("\n");
 }
 
+function attributeLabel(attribute: UserPublicAttribute): string {
+  if (attribute.kind === "tag") {
+    return `tag:${attribute.value}`;
+  }
+
+  return `${attribute.key}:${attribute.value}`;
+}
+
+function instanceTargetLabel(target: Pick<UserAttributeMessageTarget, "instanceId" | "instanceName" | "peerId">) {
+  const name = target.instanceName ? ` (${target.instanceName})` : "";
+  return `${target.instanceId}${name} -> ${target.peerId}`;
+}
+
+function formatUserAttributeTargets(targets: UserAttributeMessageTarget[]) {
+  return targets.map((target) => `${instanceTargetLabel(target)} [${attributeLabel(target.matchedAttribute)}]`);
+}
+
+function formatUserAttributeResults(results: UserAttributeMessageDeliveryResult[]) {
+  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}`;
+  });
+}
+
+type SendUserAttributeToolParams = {
+  match?: {
+    kind?: unknown;
+    key?: unknown;
+    value?: unknown;
+  };
+  message?: unknown;
+  dryRun?: unknown;
+};
+
+function normalizeUserAttributeMatch(params: SendUserAttributeToolParams): UserAttributeMatch | string {
+  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: MeshNetwork, router?: InstanceRouter) {
   return [
     {
@@ -378,5 +448,121 @@ export function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter) {
         };
       },
     },
+    {
+      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" as const,
+        properties: {
+          match: {
+            type: "object" as const,
+            description:
+              'User public attribute match. Use { "kind": "tag", "value": "..." } for USER.md tags or { "kind": "structured", "key": "...", "value": "..." } for profile attributes.',
+            oneOf: [
+              {
+                type: "object" as const,
+                additionalProperties: false,
+                properties: {
+                  kind: { const: "tag" as const },
+                  value: {
+                    type: "string" as const,
+                    description: "Tag value to match.",
+                  },
+                },
+                required: ["kind", "value"],
+              },
+              {
+                type: "object" as const,
+                additionalProperties: false,
+                properties: {
+                  kind: { const: "structured" as const },
+                  key: {
+                    type: "string" as const,
+                    description: "Structured attribute key to match.",
+                  },
+                  value: {
+                    type: "string" as const,
+                    description: "Structured attribute value to match.",
+                  },
+                },
+                required: ["kind", "key", "value"],
+              },
+            ],
+          },
+          message: {
+            type: "string" as const,
+            description: "Message content to send after dry-run target confirmation.",
+          },
+          dryRun: {
+            type: "boolean" as const,
+            description: "Preview matching instances without sending. Run this before group sending.",
+          },
+        },
+        required: ["match", "message"],
+      },
+      async execute(_toolCallId: string, params: SendUserAttributeToolParams) {
+        if (!router) {
+          return {
+            content: [{ type: "text" as const, 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" as const, 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" as const, text: result.error }],
+            details: result,
+            isError: true,
+          };
+        }
+
+        if (dryRun) {
+          const targetLines = formatUserAttributeTargets(result.targets ?? []);
+          return {
+            content: [
+              {
+                type: "text" as const,
+                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" as const,
+              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/src/instance-peer-store.ts

@@ -6,7 +6,9 @@ import type {
   InstancePeerRecord,
   InstancePeerStore,
   InstancePeerTable,
+  UserPublicAttribute,
 } from "./types.js";
+import { normalizeUserPublicAttribute } from "./user-attributes.js";
 
 export interface StoreLogger {
   info?(message: string): void;
@@ -38,21 +40,50 @@ function sameStringArray(a: string[] = [], b: string[] = []): boolean {
   return a.every((value, index) => value === b[index]);
 }
 
+function normalizeUserPublicAttributes(value: unknown): UserPublicAttribute[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value
+    .map((attribute) => normalizeUserPublicAttribute(attribute))
+    .filter((attribute): attribute is UserPublicAttribute => attribute !== undefined);
+}
+
+function sameUserPublicAttributes(a: UserPublicAttribute[] = [], b: UserPublicAttribute[] = []): boolean {
+  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: InstancePeerRecord | undefined,
   payload: InstanceAnnouncePayload,
 ): boolean {
   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: InstancePeerRecord): InstancePeerRecord {
+  return {
+    ...value,
+    userPublicAttributes: normalizeUserPublicAttributes(value.userPublicAttributes),
+  };
+}
+
 function normalizeTable(value: unknown): InstancePeerTable {
   const candidate = value && typeof value === "object" ? value : {};
   const table = candidate as Partial<InstancePeerTable>;
@@ -61,10 +92,17 @@ function normalizeTable(value: unknown): InstancePeerTable {
       ? table.instances
       : {};
 
+  const normalizedInstances: Record<string, InstancePeerRecord> = {};
+  for (const [instanceId, record] of Object.entries(instances)) {
+    if (record && typeof record === "object") {
+      normalizedInstances[instanceId] = normalizeRecord(record as InstancePeerRecord);
+    }
+  }
+
   return {
     version: 1,
     updatedAt: typeof table.updatedAt === "number" ? table.updatedAt : Date.now(),
-    instances: instances as Record<string, InstancePeerRecord>,
+    instances: normalizedInstances,
   };
 }
 
@@ -149,6 +187,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: InstancePeerRecord = {
           instanceId: payload.instanceId,
@@ -156,6 +195,7 @@ export function createInstancePeerStore(options?: {
           instanceName: payload.instanceName,
           pubkey: payload.pubkey,
           multiaddrs: payload.multiaddrs,
+          userPublicAttributes,
           lastAnnouncedAt: payload.announcedAt,
           lastSeenAt: Date.now(),
           source: "announce",

package/src/instance-router.ts

@@ -1,16 +1,18 @@
 import type {
   DeliveryAckPayload,
   DeliveryTargetResult,
-  InboundDeliveryAdapter,
   InboundTargetConfig,
   InstanceAnnouncePayload,
-  InstancePeerStore,
   InstanceRouter,
+  InstanceRouterOptions,
   MeshConfig,
-  MeshNetwork,
   P2PMessage,
+  UserAttributeMatch,
+  UserAttributeMessageTarget,
+  UserPublicAttribute,
   UserMessagePayload,
 } from "./types.js";
+import { matchesUserAttribute, mergeUserPublicAttributes } from "./user-attributes.js";
 
 export type RouterLogger = {
   info?: (message: string) => void;
@@ -48,6 +50,14 @@ function summarizeError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+function describeAttributeMatch(match: UserAttributeMatch): string {
+  if (match.kind === "tag") {
+    return `tag ${match.value}`;
+  }
+
+  return `structured attribute ${match.key}=${match.value}`;
+}
+
 type EffectiveInboundTarget = {
   id?: string;
   channel: string;
@@ -135,13 +145,7 @@ function firstAttemptedResult(
   );
 }
 
-export function createInstanceRouter(options: {
-  mesh: MeshNetwork;
-  store: InstancePeerStore;
-  delivery: InboundDeliveryAdapter;
-  config?: MeshConfig;
-  logger?: RouterLogger;
-}): InstanceRouter {
+export function createInstanceRouter(options: InstanceRouterOptions): InstanceRouter {
   const { mesh, store, delivery } = options;
   const config = options.config ?? {};
   const logger = options.logger;
@@ -159,7 +163,26 @@ export function createInstanceRouter(options: {
     return identity.id;
   }
 
-  function buildAnnouncePayload(): InstanceAnnouncePayload {
+  async function loadUserPublicAttributes(): Promise<UserPublicAttribute[]> {
+    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(): Promise<InstanceAnnouncePayload> {
     const identity = mesh.getInstanceIdentity();
     if (!identity) {
       throw new Error("Local instance identity is not initialized");
@@ -171,6 +194,7 @@ export function createInstanceRouter(options: {
       instanceName: identity.name,
       multiaddrs: mesh.getMultiaddrs(),
       pubkey: identity.pubkey,
+      userPublicAttributes: await loadUserPublicAttributes(),
       announcedAt: Date.now(),
     };
   }
@@ -180,7 +204,7 @@ export function createInstanceRouter(options: {
       return;
     }
 
-    const payload = buildAnnouncePayload();
+    const payload = await buildAnnouncePayload();
     await mesh.sendStructuredMessage(peerId, {
       id: crypto.randomUUID(),
       type: "instance-announce",
@@ -549,6 +573,90 @@ export function createInstanceRouter(options: {
     };
   }
 
+  async function resolveUserAttributeTargets(
+    match: UserAttributeMatch,
+  ): Promise<UserAttributeMessageTarget[]> {
+    const records = await store.list();
+    const targets: UserAttributeMessageTarget[] = [];
+
+    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: UserAttributeMatch,
+    message: string,
+    sendOptions: { dryRun?: boolean } = {},
+  ) {
+    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,
@@ -557,5 +665,6 @@ export function createInstanceRouter(options: {
     listInstances,
     resolveInstance,
     sendInstanceMessage,
+    sendUserAttributeMessage,
   };
 }

package/src/plugin.ts

@@ -5,13 +5,15 @@ 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";
 import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
 import type { MeshConfig } from "./types.js";
 
 export function registerLibp2pMesh(api: OpenClawPluginApi) {
-  registerLibp2pMeshSetupCli(api);
+  registerLibp2pMeshCli(api);
 
   const config = api.pluginConfig as MeshConfig | undefined;
   let unsubscribeInbound: (() => void) | undefined;
@@ -21,6 +23,8 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
     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) => {
@@ -41,6 +45,8 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
     delivery,
     config,
     logger: api.logger,
+    userAttributeSource,
+    userProfileStore,
   });
 
   const channel = createLibp2pMeshChannel(mesh);

package/src/profile-cli.ts

@@ -0,0 +1,85 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import type { OpenClawPluginCliContext } from "openclaw/plugin-sdk/plugin-runtime";
+import {
+  createReadlinePrompter,
+  LIBP2P_MESH_CLI_REGISTRATION,
+  registerLibp2pMeshSetupCommand,
+  type ClosableSetupPrompter,
+  type SetupCliDeps,
+} from "./setup-cli.js";
+import { runProfileWizard } from "./profile-wizard.js";
+import { createUserMdAttributeSource } from "./user-md-attributes.js";
+import { createUserProfileStore, 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 function registerLibp2pMeshCli(api: OpenClawPluginApi, deps: Libp2pMeshCliDeps = {}): void {
+  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: OpenClawPluginApi, deps: ProfileCliDeps = {}): void {
+  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: CliRootCommand,
+  api: OpenClawPluginApi,
+  ctx: OpenClawPluginCliContext,
+  deps: ProfileCliDeps = {},
+): void {
+  root
+    .command("profile")
+    .description("Manage libp2p-mesh public profile attributes.")
+    .action(async () => {
+      const prompter = (deps.createPrompter?.(ctx) ?? createReadlinePrompter()) as ClosableSetupPrompter;
+      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?.();
+      }
+    });
+}