libp2p-mesh 2026.6.19 → 2026.6.21

package/src/agent-tools.ts

@@ -1,8 +1,12 @@
 import type {
   DeliveryTargetResult,
+  InstancePeerRecord,
   InstanceRouter,
+  LocalPeerLabelAttribute,
   MeshNetwork,
+  PeerLabelStore,
   UserAttributeMatch,
+  UserAttributeMatchScope,
   UserAttributeMessageDeliveryResult,
   UserAttributeMessageTarget,
   UserPublicAttribute,
@@ -28,7 +32,7 @@ function formatDeliveryResults(
   return [heading, ...lines].join("\n");
 }
 
-function attributeLabel(attribute: UserPublicAttribute): string {
+function attributeLabel(attribute: UserPublicAttribute | LocalPeerLabelAttribute): string {
   if (attribute.kind === "tag") {
     return `tag:${attribute.value}`;
   }
@@ -42,7 +46,7 @@ function instanceTargetLabel(target: Pick<UserAttributeMessageTarget, "instanceI
 }
 
 function formatUserAttributeTargets(targets: UserAttributeMessageTarget[]) {
-  return targets.map((target) => `${instanceTargetLabel(target)} [${attributeLabel(target.matchedAttribute)}]`);
+  return targets.map((target) => `${instanceTargetLabel(target)} [${target.matchSource}:${attributeLabel(target.matchedAttribute)}]`);
 }
 
 function formatUserAttributeResults(results: UserAttributeMessageDeliveryResult[]) {
@@ -58,6 +62,82 @@ function formatUserAttributeResults(results: UserAttributeMessageDeliveryResult[
   });
 }
 
+type ListInstanceRow = InstancePeerRecord & {
+  connected: boolean;
+  localLabels: LocalPeerLabelAttribute[];
+};
+
+type BuildP2PToolsOptions = {
+  peerLabelStore?: Pick<PeerLabelStore, "listLabels">;
+};
+
+function formatPublicAttribute(attribute: UserPublicAttribute): string[] {
+  if (attribute.kind === "tag") {
+    return [
+      "     - kind: tag",
+      `       value: ${attribute.value}`,
+      `       label: ${attribute.label}`,
+      `       source: ${attribute.source}`,
+    ];
+  }
+
+  return [
+    "     - kind: structured",
+    `       key: ${attribute.key}`,
+    `       value: ${attribute.value}`,
+    `       label: ${attribute.label}`,
+    `       source: ${attribute.source}`,
+  ];
+}
+
+function formatLocalLabel(label: LocalPeerLabelAttribute): string[] {
+  return [
+    "     - kind: structured",
+    `       key: ${label.key}`,
+    `       value: ${label.value}`,
+    `       label: ${label.label}`,
+    `       source: ${label.source}`,
+  ];
+}
+
+function formatInstanceList(rows: ListInstanceRow[]): string {
+  if (rows.length === 0) {
+    return "No OpenClaw instances discovered yet.";
+  }
+
+  const lines = [`Discovered OpenClaw instances: ${rows.length}`];
+
+  rows.forEach((entry, index) => {
+    lines.push(
+      "",
+      `${index + 1}. ${entry.instanceId}`,
+      `   peerId: ${entry.peerId}`,
+      `   instanceName: ${entry.instanceName ?? "(none)"}`,
+      `   connected: ${entry.connected}`,
+    );
+
+    if ((entry.userPublicAttributes ?? []).length === 0) {
+      lines.push("   userPublicAttributes: none");
+    } else {
+      lines.push("   userPublicAttributes:");
+      for (const attribute of entry.userPublicAttributes ?? []) {
+        lines.push(...formatPublicAttribute(attribute));
+      }
+    }
+
+    if (entry.localLabels.length === 0) {
+      lines.push("   localLabels: none");
+    } else {
+      lines.push("   localLabels:");
+      for (const label of entry.localLabels) {
+        lines.push(...formatLocalLabel(label));
+      }
+    }
+  });
+
+  return lines.join("\n");
+}
+
 type SendUserAttributeToolParams = {
   selector?: unknown;
   match?: {
@@ -67,8 +147,34 @@ type SendUserAttributeToolParams = {
   };
   message?: unknown;
   dryRun?: unknown;
+  scope?: unknown;
 };
 
+function normalizeUserAttributeScope(scope: unknown): UserAttributeMatchScope | undefined {
+  if (scope === undefined) {
+    return undefined;
+  }
+
+  if (scope === "public" || scope === "local" || scope === "all") {
+    return scope;
+  }
+
+  return undefined;
+}
+
+function validateUserAttributeScope(scope: unknown): string | undefined {
+  if (
+    scope === undefined ||
+    scope === "public" ||
+    scope === "local" ||
+    scope === "all"
+  ) {
+    return undefined;
+  }
+
+  return 'scope must be "public", "local", or "all".';
+}
+
 function normalizeUserAttributeSelector(selector: unknown): UserAttributeMatch | string {
   const value = typeof selector === "string" ? selector.trim() : "";
   if (!value) {
@@ -124,7 +230,11 @@ function normalizeUserAttributeMatch(params: SendUserAttributeToolParams): UserA
   return 'match.kind must be "tag" or "structured".';
 }
 
-export function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter) {
+export function buildP2PTools(
+  mesh: MeshNetwork,
+  router?: InstanceRouter,
+  options: BuildP2PToolsOptions = {},
+) {
   return [
     {
       name: "p2p_send_message",
@@ -334,19 +444,17 @@ export function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter) {
         try {
           const instances = await router.listInstances();
           const connected = new Set(mesh.getConnectedPeers());
-          const rows = instances.map((entry) => ({
-            ...entry,
-            connected: connected.has(entry.peerId),
-          }));
-          const text =
-            rows.length === 0
-              ? "No OpenClaw instances discovered yet."
-              : rows
-                  .map(
-                    (entry) =>
-                      `${entry.instanceId} -> ${entry.peerId}${entry.connected ? " (connected)" : ""}`,
-                  )
-                  .join("\n");
+          const rows = await Promise.all(
+            instances.map(async (entry): Promise<ListInstanceRow> => ({
+              ...entry,
+              userPublicAttributes: entry.userPublicAttributes ?? [],
+              connected: connected.has(entry.peerId),
+              localLabels: options.peerLabelStore
+                ? await options.peerLabelStore.listLabels(entry.instanceId)
+                : [],
+            })),
+          );
+          const text = formatInstanceList(rows);
           return {
             content: [{ type: "text" as const, text }],
             details: { instances: rows, count: rows.length },
@@ -486,7 +594,7 @@ 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 selector. Use selectors like "group=实验室", "project=小龙虾", "tag:P2P", or "#P2P". First run a dry run with dryRun=true to preview targets; if targets match, call again immediately with dryRun=false and the same selector.',
+        'Send a user message to discovered OpenClaw instances matching an attribute selector. scope controls the source: "public" for announced user attributes, "local" for local peer labels, or "all" for both; defaults to public. Use selectors like "group=实验室", "project=小龙虾", "tag:P2P", or "#P2P". First run a dry run with dryRun=true to preview targets; if targets match, call again immediately with dryRun=false and the same selector, scope, and message.',
       parameters: {
         type: "object" as const,
         properties: {
@@ -539,8 +647,15 @@ export function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter) {
             type: "boolean" as const,
             description: "Preview matching instances without sending. Run this before group sending.",
           },
+          scope: {
+            type: "string" as const,
+            enum: ["public", "local", "all"],
+            description:
+              "Attribute source to match: public announced attributes, local peer labels, or both. Defaults to public.",
+          },
         },
-        required: ["selector", "message"],
+        required: ["message"],
+        anyOf: [{ required: ["selector"] }, { required: ["match"] }],
       },
       async execute(_toolCallId: string, params: SendUserAttributeToolParams) {
         if (!router) {
@@ -552,9 +667,16 @@ export function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter) {
         }
 
         const match = normalizeUserAttributeMatch(params);
+        const scopeError = validateUserAttributeScope(params.scope);
+        const scope = normalizeUserAttributeScope(params.scope);
         const message = typeof params.message === "string" ? params.message.trim() : "";
-        if (typeof match === "string" || !message) {
-          const error = typeof match === "string" ? match : "message is required.";
+        if (typeof match === "string" || scopeError || !message) {
+          const error =
+            typeof match === "string"
+              ? match
+              : scopeError
+                ? scopeError
+                : "message is required.";
           return {
             content: [{ type: "text" as const, text: error }],
             details: { error },
@@ -563,7 +685,8 @@ export function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter) {
         }
 
         const dryRun = params.dryRun === true;
-        const result = await router.sendUserAttributeMessage(match, message, { dryRun });
+        const options = scope ? { dryRun, scope } : { dryRun };
+        const result = await router.sendUserAttributeMessage(match, message, options);
         if (result.error) {
           return {
             content: [{ type: "text" as const, text: result.error }],

package/src/instance-peer-store.ts

@@ -66,13 +66,15 @@ function sameRecord(
 
   const recordAttributes = normalizeUserPublicAttributes(record.userPublicAttributes);
   const payloadAttributes = normalizeUserPublicAttributes(payload.userPublicAttributes);
+  const payloadIncludesAttributes = "userPublicAttributes" in payload;
 
   return (
     record.peerId === payload.peerId &&
     record.instanceName === payload.instanceName &&
     record.pubkey === payload.pubkey &&
     sameStringArray(record.multiaddrs, payload.multiaddrs) &&
-    sameUserPublicAttributes(recordAttributes, payloadAttributes) &&
+    (!payloadIncludesAttributes ||
+      sameUserPublicAttributes(recordAttributes, payloadAttributes)) &&
     record.lastAnnouncedAt === payload.announcedAt
   );
 }
@@ -187,7 +189,10 @@ export function createInstancePeerStore(options?: {
       return runMutation(async () => {
         const table = await load();
         const existing = table.instances[payload.instanceId];
-        const userPublicAttributes = normalizeUserPublicAttributes(payload.userPublicAttributes);
+        const userPublicAttributes =
+          "userPublicAttributes" in payload
+            ? normalizeUserPublicAttributes(payload.userPublicAttributes)
+            : normalizeUserPublicAttributes(existing?.userPublicAttributes);
         const changed = !sameRecord(existing, payload);
         const record: InstancePeerRecord = {
           instanceId: payload.instanceId,

package/src/instance-router.ts

@@ -6,14 +6,23 @@ import type {
   InstanceAnnouncePayload,
   InstanceRouter,
   InstanceRouterOptions,
+  LocalPeerLabelAttribute,
   MeshConfig,
   P2PMessage,
   UserAttributeMatch,
+  UserAttributeMessageOptions,
+  UserAttributeMatchScope,
+  UserAttributeMatchSource,
   UserAttributeMessageTarget,
   UserPublicAttribute,
   UserMessagePayload,
 } from "./types.js";
-import { matchesUserAttribute, mergeUserPublicAttributes } from "./user-attributes.js";
+import {
+  matchesUserAttribute,
+  mergeUserPublicAttributes,
+  normalizeAttributeKey,
+  normalizeAttributeValue,
+} from "./user-attributes.js";
 
 export type RouterLogger = {
   info?: (message: string) => void;
@@ -77,6 +86,40 @@ function describeAttributeMatch(match: UserAttributeMatch): string {
   return `structured attribute ${match.key}=${match.value}`;
 }
 
+function effectiveAttributeMatchScope(
+  scope: UserAttributeMatchScope | undefined,
+): UserAttributeMatchScope {
+  return scope ?? "public";
+}
+
+function matchesLocalPeerLabel(
+  attribute: LocalPeerLabelAttribute,
+  match: UserAttributeMatch,
+): boolean {
+  if (match.kind !== "structured") {
+    return false;
+  }
+
+  return (
+    normalizeAttributeKey(attribute.key) === normalizeAttributeKey(match.key) &&
+    normalizeAttributeValue(attribute.value) === normalizeAttributeValue(match.value)
+  );
+}
+
+function buildUserAttributeTarget(
+  record: { instanceId: string; instanceName?: string; peerId: string },
+  matchedAttribute: UserPublicAttribute | LocalPeerLabelAttribute,
+  matchSource: UserAttributeMatchSource,
+): UserAttributeMessageTarget {
+  return {
+    instanceId: record.instanceId,
+    ...(record.instanceName ? { instanceName: record.instanceName } : {}),
+    peerId: record.peerId,
+    matchedAttribute,
+    matchSource,
+  };
+}
+
 type EffectiveInboundTarget = {
   id?: string;
   channel: string;
@@ -174,6 +217,8 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
   const pendingAcks = new Map<string, PendingAck>();
   const deliveryCache = new Map<string, DeliveryCacheEntry>();
   const unsubs: Array<() => void> = [];
+  const pendingAttributePeers = new Set<string>();
+  let attributeRefreshPromise: Promise<void> | undefined;
 
   function localInstanceId(): string {
     const identity = mesh.getInstanceIdentity();
@@ -183,26 +228,35 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
     return identity.id;
   }
 
-  async function loadUserPublicAttributes(): Promise<UserPublicAttribute[]> {
-    const [userMdTags, profileAttributes] = await Promise.all([
-      options.userAttributeSource?.loadTags().catch((error) => {
+  async function loadUserPublicAttributes(loadOptions?: {
+    refreshUserMd?: boolean;
+  }): Promise<UserPublicAttribute[]> {
+    const userMdPromise = loadOptions?.refreshUserMd && options.userAttributeSource?.refreshTags
+      ? options.userAttributeSource.refreshTags()
+      : options.userAttributeSource?.loadTags() ?? Promise.resolve([]);
+
+    const profilePromise =
+      options.userProfileStore?.listAttributes().catch((error) => {
         logger?.warn?.(
-          `[libp2p-mesh] Failed to load USER.md public attributes: ${summarizeError(error)}`,
+          `[libp2p-mesh] Failed to load profile public attributes: ${summarizeError(error)}`,
         );
         return [];
-      }) ?? Promise.resolve([]),
-      options.userProfileStore?.listAttributes().catch((error) => {
+      }) ?? Promise.resolve([]);
+
+    const [userMdTags, profileAttributes] = await Promise.all([
+      userMdPromise.catch((error) => {
         logger?.warn?.(
-          `[libp2p-mesh] Failed to load profile public attributes: ${summarizeError(error)}`,
+          `[libp2p-mesh] Failed to load USER.md public attributes: ${summarizeError(error)}`,
         );
         return [];
-      }) ?? Promise.resolve([]),
+      }),
+      profilePromise,
     ]);
 
     return mergeUserPublicAttributes(userMdTags, profileAttributes);
   }
 
-  async function buildAnnouncePayload(): Promise<InstanceAnnouncePayload> {
+  function buildBaseAnnouncePayload(): InstanceAnnouncePayload {
     const identity = mesh.getInstanceIdentity();
     if (!identity) {
       throw new Error("Local instance identity is not initialized");
@@ -214,17 +268,102 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
       instanceName: identity.name,
       multiaddrs: mesh.getMultiaddrs(),
       pubkey: identity.pubkey,
-      userPublicAttributes: await loadUserPublicAttributes(),
       announcedAt: Date.now(),
     };
   }
 
+  async function buildAttributeAnnouncePayload(): Promise<InstanceAnnouncePayload> {
+    return {
+      ...buildBaseAnnouncePayload(),
+      userPublicAttributes: await loadUserPublicAttributes({ refreshUserMd: true }),
+    };
+  }
+
+  function attributeAnnouncePeers(extraPeerId?: string): string[] {
+    const peers = new Set<string>();
+    for (const peerId of mesh.getConnectedPeers()) {
+      if (isNonEmptyString(peerId) && peerId !== mesh.getLocalPeerId()) {
+        peers.add(peerId);
+      }
+    }
+    for (const peerId of announcedPeers) {
+      if (isNonEmptyString(peerId) && peerId !== mesh.getLocalPeerId()) {
+        peers.add(peerId);
+      }
+    }
+    if (extraPeerId && extraPeerId !== mesh.getLocalPeerId()) {
+      peers.add(extraPeerId);
+    }
+    return [...peers];
+  }
+
+  async function sendAttributeAnnounceToPeers(peers: string[]): Promise<void> {
+    if (peers.length === 0) {
+      return;
+    }
+
+    const payload = await buildAttributeAnnouncePayload();
+    for (const peerId of peers) {
+      try {
+        await mesh.sendStructuredMessage(peerId, {
+          id: crypto.randomUUID(),
+          type: "instance-announce",
+          to: peerId,
+          payload: JSON.stringify(payload),
+        });
+        logAnnounce("Sent", peerId, payload);
+      } catch (error) {
+        logger?.warn?.(
+          `[libp2p-mesh] Failed to send attribute announce to ${peerId}: ${summarizeError(error)}`,
+        );
+      }
+    }
+  }
+
+  function queueAttributeRefresh(extraPeerId?: string): void {
+    const peers =
+      extraPeerId === undefined
+        ? attributeAnnouncePeers()
+        : isNonEmptyString(extraPeerId) && extraPeerId !== mesh.getLocalPeerId()
+          ? [extraPeerId]
+          : [];
+    for (const peerId of peers) {
+      pendingAttributePeers.add(peerId);
+    }
+
+    if (pendingAttributePeers.size === 0 && !attributeRefreshPromise) {
+      return;
+    }
+
+    drainAttributeRefresh();
+  }
+
+  function drainAttributeRefresh(): Promise<void> {
+    if (!attributeRefreshPromise) {
+      attributeRefreshPromise = (async () => {
+        while (pendingAttributePeers.size > 0) {
+          const peers = [...pendingAttributePeers];
+          pendingAttributePeers.clear();
+          await sendAttributeAnnounceToPeers(peers).catch((error) => {
+            logger?.warn?.(
+              `[libp2p-mesh] Failed to refresh public attributes: ${summarizeError(error)}`,
+            );
+          });
+        }
+      })().finally(() => {
+        attributeRefreshPromise = undefined;
+      });
+    }
+
+    return attributeRefreshPromise;
+  }
+
   async function announceToPeer(peerId: string): Promise<void> {
     if (!isNonEmptyString(peerId) || peerId === mesh.getLocalPeerId()) {
       return;
     }
 
-    const payload = await buildAnnouncePayload();
+    const payload = buildBaseAnnouncePayload();
     await mesh.sendStructuredMessage(peerId, {
       id: crypto.randomUUID(),
       type: "instance-announce",
@@ -233,6 +372,15 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
     });
     announcedPeers.add(peerId);
     logAnnounce("Sent", peerId, payload);
+    queueAttributeRefresh(peerId);
+  }
+
+  async function refreshPublicAttributes(): Promise<void> {
+    for (const peerId of attributeAnnouncePeers()) {
+      pendingAttributePeers.add(peerId);
+    }
+
+    await drainAttributeRefresh();
   }
 
   function announceSummary(
@@ -638,24 +786,38 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
 
   async function resolveUserAttributeTargets(
     match: UserAttributeMatch,
+    scope: UserAttributeMatchScope,
   ): 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) {
+      const publicAttribute =
+        scope === "local"
+          ? undefined
+          : record.userPublicAttributes?.find((attribute) =>
+              matchesUserAttribute(attribute, match),
+            );
+      const localAttribute =
+        scope === "public"
+          ? undefined
+          : (await options.peerLabelStore?.listLabels(record.instanceId))?.find((attribute) =>
+              matchesLocalPeerLabel(attribute, match),
+            );
+
+      if (publicAttribute && localAttribute && scope === "all") {
+        targets.push(buildUserAttributeTarget(record, publicAttribute, "all"));
         continue;
       }
 
-      targets.push({
-        instanceId: record.instanceId,
-        instanceName: record.instanceName,
-        peerId: record.peerId,
-        matchedAttribute,
-      });
+      if (publicAttribute) {
+        targets.push(buildUserAttributeTarget(record, publicAttribute, "public"));
+        continue;
+      }
+
+      if (localAttribute) {
+        targets.push(buildUserAttributeTarget(record, localAttribute, "local"));
+      }
     }
 
     return targets;
@@ -664,11 +826,16 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
   async function sendUserAttributeMessage(
     match: UserAttributeMatch,
     message: string,
-    sendOptions: { dryRun?: boolean } = {},
+    sendOptions: UserAttributeMessageOptions = {},
   ) {
-    const targets = await resolveUserAttributeTargets(match);
+    const scope = effectiveAttributeMatchScope(sendOptions.scope);
+    const targets = await resolveUserAttributeTargets(
+      match,
+      scope,
+    );
     if (targets.length === 0) {
       return {
+        scope,
         matched: 0,
         sent: 0,
         delivered: 0,
@@ -679,6 +846,7 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
 
     if (sendOptions.dryRun === true) {
       return {
+        scope,
         matched: targets.length,
         sent: 0,
         delivered: 0,
@@ -712,6 +880,7 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
     }
 
     return {
+      scope,
       matched: targets.length,
       sent: results.filter((result) => result.sent).length,
       delivered: results.filter((result) => result.delivered).length,
@@ -727,6 +896,7 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
     stop,
     handleMessage,
     announceToPeer,
+    refreshPublicAttributes,
     listInstances,
     resolveInstance,
     sendInstanceMessage,