libp2p-mesh 2026.6.19 → 2026.6.21

package/src/types.ts

@@ -102,10 +102,51 @@ export type UserPublicAttribute =
       source: "profile";
     };
 
+export type UserMdAttributeSource = {
+  loadTags(): Promise<UserPublicAttribute[]>;
+  refreshTags?(): Promise<UserPublicAttribute[]>;
+};
+
+export type LocalPeerLabel = {
+  key: string;
+  value: string;
+};
+
+export type LocalPeerLabelAttribute = {
+  kind: "structured";
+  key: string;
+  value: string;
+  label: string;
+  source: "local";
+};
+
+export type PeerLabelsFile = {
+  version: 1;
+  updatedAt: number;
+  peers: Record<string, { labels: LocalPeerLabel[] }>;
+};
+
+export type PeerLabelStore = {
+  load(): Promise<PeerLabelsFile>;
+  save(file: PeerLabelsFile): Promise<PeerLabelsFile>;
+  listRawLabels(instanceId: string): Promise<LocalPeerLabel[]>;
+  listLabels(instanceId: string): Promise<LocalPeerLabelAttribute[]>;
+  replaceLabels(instanceId: string, labels: LocalPeerLabel[]): Promise<PeerLabelsFile>;
+};
+
 export type UserAttributeMatch =
   | { kind: "tag"; value: string }
   | { kind: "structured"; key: string; value: string };
 
+export type UserAttributeMatchScope = "public" | "local" | "all";
+
+export type UserAttributeMatchSource = "public" | "local" | "all";
+
+export type UserAttributeMessageOptions = {
+  dryRun?: boolean;
+  scope?: UserAttributeMatchScope;
+};
+
 export interface InstancePeerRecord {
   instanceId: string;
   peerId: string;
@@ -139,7 +180,8 @@ export type UserAttributeMessageTarget = {
   instanceId: string;
   instanceName?: string;
   peerId: string;
-  matchedAttribute: UserPublicAttribute;
+  matchedAttribute: UserPublicAttribute | LocalPeerLabelAttribute;
+  matchSource: UserAttributeMatchSource;
 };
 
 export type UserAttributeMessageDeliveryResult = UserAttributeMessageTarget & {
@@ -149,6 +191,7 @@ export type UserAttributeMessageDeliveryResult = UserAttributeMessageTarget & {
 };
 
 export type UserAttributeMessageResult = {
+  scope: UserAttributeMatchScope;
   matched: number;
   sent: number;
   delivered: number;
@@ -194,12 +237,13 @@ export type InstanceRouterOptions = {
     warn?: (message: string) => void;
     error?: (message: string) => void;
   };
-  userAttributeSource?: {
-    loadTags(): Promise<UserPublicAttribute[]>;
-  };
+  userAttributeSource?: UserMdAttributeSource;
   userProfileStore?: {
     listAttributes(): Promise<UserPublicAttribute[]>;
   };
+  peerLabelStore?: {
+    listLabels(instanceId: string): Promise<LocalPeerLabelAttribute[]>;
+  };
 };
 
 export interface InstanceRouter {
@@ -209,6 +253,7 @@ export interface InstanceRouter {
   stop(): Promise<void>;
   handleMessage(msg: P2PMessage): Promise<void>;
   announceToPeer(peerId: string): Promise<void>;
+  refreshPublicAttributes(): Promise<void>;
   listInstances(): Promise<InstancePeerRecord[]>;
   resolveInstance(instanceId: string): Promise<InstancePeerRecord | undefined>;
   sendInstanceMessage(instanceId: string, message: string): Promise<{
@@ -225,7 +270,7 @@ export interface InstanceRouter {
   sendUserAttributeMessage(
     match: UserAttributeMatch,
     message: string,
-    options?: { dryRun?: boolean },
+    options?: UserAttributeMessageOptions,
   ): Promise<UserAttributeMessageResult>;
 }
 

package/src/user-md-agent-attributes.ts

@@ -0,0 +1,243 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+
+import type { UserMdAttributeSource, UserPublicAttribute } from "./types.js";
+import { normalizeAttributeValue } from "./user-attributes.js";
+import { resolveUserMdPath } from "./user-md-attributes.js";
+
+const CACHE_VERSION = 1;
+const MAX_AGENT_TAGS = 10;
+const MAX_AGENT_TAG_LENGTH = 40;
+
+type Logger = {
+  debug?: (message: string) => void;
+  warn?: (message: string) => void;
+};
+
+type UserMdAttributeCacheFile = {
+  version: 1;
+  updatedAt: number;
+  userMdHash: string;
+  attributes: UserPublicAttribute[];
+};
+
+export type UserMdAttributeExtractionUnavailable = {
+  unavailable: true;
+  reason: string;
+};
+
+export type UserMdAttributeExtractor = {
+  extract(request: {
+    markdown: string;
+    sourcePath: string;
+  }): Promise<UserPublicAttribute[] | UserMdAttributeExtractionUnavailable>;
+};
+
+const defaultExtractor: UserMdAttributeExtractor = {
+  async extract() {
+    return {
+      unavailable: true,
+      reason: "USER.md agent extraction is unavailable in this runtime",
+    };
+  },
+};
+
+export function resolveUserMdAttributeCachePath(customPath?: string): string {
+  if (customPath) {
+    return customPath;
+  }
+
+  const stateDir = process.env.OPENCLAW_STATE_DIR;
+  if (stateDir) {
+    return path.join(stateDir, "libp2p", "user-md-attributes-cache.json");
+  }
+
+  return path.join(homedir(), ".openclaw", "libp2p", "user-md-attributes-cache.json");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function normalizeWhitespace(value: string): string {
+  return value.trim().replace(/\s+/g, " ");
+}
+
+function looksLikeSentence(value: string): boolean {
+  return /[。.!?！？]/.test(value) || value.split(/\s+/).filter(Boolean).length > 4;
+}
+
+function normalizeAgentTag(value: unknown): UserPublicAttribute | undefined {
+  if (!isRecord(value) || value.kind !== "tag" || value.source !== "USER.md") {
+    return undefined;
+  }
+
+  if (typeof value.value !== "string" || typeof value.label !== "string") {
+    return undefined;
+  }
+
+  const tagValue = normalizeWhitespace(value.value);
+  const label = normalizeWhitespace(value.label);
+  if (!tagValue || !label || tagValue.length > MAX_AGENT_TAG_LENGTH || looksLikeSentence(tagValue)) {
+    return undefined;
+  }
+
+  return {
+    kind: "tag",
+    value: tagValue,
+    label,
+    source: "USER.md",
+  };
+}
+
+export function validateExtractedUserMdTags(value: unknown): UserPublicAttribute[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  const attributes: UserPublicAttribute[] = [];
+  const seen = new Set<string>();
+
+  for (const rawAttribute of value) {
+    const attribute = normalizeAgentTag(rawAttribute);
+    if (!attribute) {
+      continue;
+    }
+
+    const key = normalizeAttributeValue(attribute.value);
+    if (seen.has(key)) {
+      continue;
+    }
+
+    seen.add(key);
+    attributes.push(attribute);
+    if (attributes.length >= MAX_AGENT_TAGS) {
+      break;
+    }
+  }
+
+  return attributes;
+}
+
+function hashMarkdown(markdown: string): string {
+  return createHash("sha256").update(markdown, "utf8").digest("hex");
+}
+
+function normalizeCacheFile(value: unknown): UserMdAttributeCacheFile | undefined {
+  if (!isRecord(value) || value.version !== CACHE_VERSION || typeof value.userMdHash !== "string") {
+    return undefined;
+  }
+
+  const attributes = validateExtractedUserMdTags(value.attributes);
+  if (!Array.isArray(value.attributes) || attributes.length !== value.attributes.length) {
+    return undefined;
+  }
+
+  return {
+    version: CACHE_VERSION,
+    updatedAt: typeof value.updatedAt === "number" ? value.updatedAt : Date.now(),
+    userMdHash: value.userMdHash,
+    attributes,
+  };
+}
+
+async function readCache(cachePath: string): Promise<UserMdAttributeCacheFile | undefined> {
+  try {
+    return normalizeCacheFile(JSON.parse(await readFile(cachePath, "utf8")));
+  } catch {
+    return undefined;
+  }
+}
+
+async function writeCache(cachePath: string, userMdHash: string, attributes: UserPublicAttribute[]): Promise<void> {
+  const cache: UserMdAttributeCacheFile = {
+    version: CACHE_VERSION,
+    updatedAt: Date.now(),
+    userMdHash,
+    attributes: validateExtractedUserMdTags(attributes),
+  };
+  const dir = path.dirname(cachePath);
+  const tmpPath = `${cachePath}.tmp-${process.pid}-${Date.now()}-${randomUUID()}`;
+
+  await mkdir(dir, { recursive: true });
+  try {
+    await writeFile(tmpPath, `${JSON.stringify(cache, null, 2)}\n`, "utf8");
+    await rename(tmpPath, cachePath);
+  } catch (error) {
+    await rm(tmpPath, { force: true }).catch(() => undefined);
+    throw error;
+  }
+}
+
+function isExtractionUnavailable(value: unknown): value is UserMdAttributeExtractionUnavailable {
+  return isRecord(value) && value.unavailable === true && typeof value.reason === "string";
+}
+
+export function createUserMdAgentAttributeSource(options?: {
+  path?: string;
+  cachePath?: string;
+  extractor?: UserMdAttributeExtractor;
+  logger?: Logger;
+}): UserMdAttributeSource {
+  const filePath = resolveUserMdPath(options?.path);
+  const cachePath = resolveUserMdAttributeCachePath(options?.cachePath);
+  const extractor = options?.extractor ?? defaultExtractor;
+  const logger = options?.logger;
+
+  async function readUserMd(): Promise<{ markdown: string; userMdHash: string } | undefined> {
+    try {
+      const markdown = await readFile(filePath, "utf8");
+      return { markdown, userMdHash: hashMarkdown(markdown) };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        return undefined;
+      }
+
+      logger?.warn?.(`[libp2p-mesh] Failed to read USER.md at ${filePath}: ${(error as Error).message}`);
+      return undefined;
+    }
+  }
+
+  async function loadCachedTagsForCurrentHash(): Promise<UserPublicAttribute[]> {
+    const userMd = await readUserMd();
+    if (!userMd) {
+      return [];
+    }
+
+    const cache = await readCache(cachePath);
+    return cache?.userMdHash === userMd.userMdHash ? [...cache.attributes] : [];
+  }
+
+  return {
+    async loadTags(): Promise<UserPublicAttribute[]> {
+      return loadCachedTagsForCurrentHash();
+    },
+    async refreshTags(): Promise<UserPublicAttribute[]> {
+      const userMd = await readUserMd();
+      if (!userMd) {
+        return [];
+      }
+
+      const cache = await readCache(cachePath);
+      if (cache?.userMdHash === userMd.userMdHash) {
+        return [...cache.attributes];
+      }
+
+      const extracted = await extractor.extract({
+        markdown: userMd.markdown,
+        sourcePath: filePath,
+      });
+      if (isExtractionUnavailable(extracted)) {
+        logger?.warn?.(`[libp2p-mesh] USER.md agent extraction unavailable: ${extracted.reason}`);
+        return [];
+      }
+
+      const attributes = validateExtractedUserMdTags(extracted);
+      await writeCache(cachePath, userMd.userMdHash, attributes);
+      logger?.debug?.(`[libp2p-mesh] Saved USER.md agent attribute cache to ${cachePath}`);
+      return attributes;
+    },
+  };
+}