libp2p-mesh 2026.6.13 → 2026.6.15

package/openclaw.plugin.json

@@ -35,6 +35,12 @@
             "type": "string",
             "default": "openclaw-mesh"
           },
+          "announceLogDetail": {
+            "type": "string",
+            "enum": ["off", "summary", "payload"],
+            "default": "summary",
+            "description": "Controls instance announce logging detail."
+          },
           "inboundTargets": {
             "type": "array",
             "items": {
@@ -82,6 +88,12 @@
         "type": "string",
         "default": "openclaw-mesh"
       },
+      "announceLogDetail": {
+        "type": "string",
+        "enum": ["off", "summary", "payload"],
+        "default": "summary",
+        "description": "Controls instance announce logging detail."
+      },
       "enablePubsub": {
         "type": "boolean",
         "default": true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libp2p-mesh",
-  "version": "2026.6.13",
+  "version": "2026.6.15",
   "description": "OpenClaw libp2p P2P mesh network plugin for cross-instance agent communication",
   "type": "module",
   "main": "dist/index.js",

package/src/debug-cli.ts

@@ -0,0 +1,93 @@
+import type { OpenClawConfig, OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import type { OpenClawPluginCliContext } from "openclaw/plugin-sdk/plugin-runtime";
+import {
+  createReadlinePrompter,
+  LIBP2P_MESH_CLI_REGISTRATION,
+  type ClosableSetupPrompter,
+} from "./setup-cli.js";
+import {
+  applyAnnounceLogDetail,
+  getAnnounceLogDetail,
+  type OpenClawConfigLike,
+} from "./setup-config.js";
+import type { SetupPrompter } from "./setup-wizard.js";
+import { runDebugWizard } from "./debug-wizard.js";
+import type { AnnounceLogDetail } from "./types.js";
+
+const DEBUG_CLI_AFTER_WRITE = {
+  mode: "none",
+  reason: "libp2p-mesh debug config updated; restart manually to apply gateway changes.",
+} as const;
+
+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 function registerLibp2pMeshDebugCli(api: OpenClawPluginApi, deps: DebugCliDeps = {}): void {
+  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: CliRootCommand,
+  api: OpenClawPluginApi,
+  ctx: OpenClawPluginCliContext,
+  deps: DebugCliDeps = {},
+): void {
+  root
+    .command("debug")
+    .description("Manage libp2p-mesh debug logging config.")
+    .action(async () => {
+      const prompter = (deps.createPrompter?.(ctx) ?? createReadlinePrompter()) as ClosableSetupPrompter;
+      const writer = deps.createWriter?.(api) ?? createOpenClawDebugConfigWriter(api);
+      try {
+        const result = await runDebugWizard({
+          prompter,
+          current: getAnnounceLogDetail(ctx.config as OpenClawConfigLike),
+          writer,
+        });
+        prompter.print(result.message);
+      } finally {
+        prompter.close?.();
+      }
+    });
+}
+
+function createOpenClawDebugConfigWriter(api: OpenClawPluginApi): DebugConfigWriter {
+  return {
+    async saveAnnounceLogDetail(detail) {
+      await api.runtime.config.mutateConfigFile({
+        afterWrite: DEBUG_CLI_AFTER_WRITE,
+        mutate(draft) {
+          const nextConfig = applyAnnounceLogDetail(draft as OpenClawConfigLike, detail);
+          replaceConfig(draft as OpenClawConfig, nextConfig as OpenClawConfig);
+        },
+      });
+    },
+  };
+}
+
+function replaceConfig(draft: OpenClawConfig, nextConfig: OpenClawConfig): void {
+  for (const key of Object.keys(draft) as Array<keyof OpenClawConfig>) {
+    delete draft[key];
+  }
+  Object.assign(draft, structuredClone(nextConfig));
+}

package/src/debug-wizard.ts

@@ -0,0 +1,64 @@
+import { SetupCancelledError, type SetupPrompter } from "./setup-wizard.js";
+import type { AnnounceLogDetail } from "./types.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 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 async function runDebugWizard(options: RunDebugWizardOptions): Promise<DebugWizardResult> {
+  try {
+    options.prompter.print(`Current announceLogDetail: ${options.current}`);
+    const selected = await options.prompter.select<DebugPromptChoice>("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(): DebugWizardResult {
+  return {
+    status: "cancelled",
+    message: CANCELLED_MESSAGE,
+  };
+}

package/src/instance-router.ts

@@ -1,4 +1,5 @@
 import type {
+  AnnounceLogDetail,
   DeliveryAckPayload,
   DeliveryTargetResult,
   InboundTargetConfig,
@@ -50,6 +51,20 @@ function summarizeError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+function effectiveAnnounceLogDetail(value: unknown): AnnounceLogDetail {
+  if (value === "off" || value === "payload") {
+    return value;
+  }
+
+  return "summary";
+}
+
+function countAnnounceAttributes(payload: InstanceAnnouncePayload): number {
+  return Array.isArray(payload.userPublicAttributes)
+    ? payload.userPublicAttributes.length
+    : 0;
+}
+
 function describeAttributeMatch(match: UserAttributeMatch): string {
   if (match.kind === "tag") {
     return `tag ${match.value}`;
@@ -149,6 +164,7 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
   const { mesh, store, delivery } = options;
   const config = options.config ?? {};
   const logger = options.logger;
+  const announceLogDetail = effectiveAnnounceLogDetail(config.announceLogDetail);
   const ackTimeoutMs = config.deliveryAckTimeoutMs ?? 15000;
   const announcedPeers = new Set<string>();
   const pendingAcks = new Map<string, PendingAck>();
@@ -212,9 +228,46 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
       payload: JSON.stringify(payload),
     });
     announcedPeers.add(peerId);
-    logger?.info?.(
-      `[libp2p-mesh] Sent instance announce to ${peerId} (${payload.instanceId})`,
-    );
+    logAnnounce("Sent", peerId, payload);
+  }
+
+  function announceSummary(
+    direction: "Sent" | "Received",
+    peerId: string,
+    payload: InstanceAnnouncePayload,
+    changed?: boolean,
+  ): string {
+    const changedDetail = changed === undefined ? "" : ` changed=${changed}`;
+    return `[libp2p-mesh] ${direction} instance announce peer=${peerId} instance=${payload.instanceId} addrs=${payload.multiaddrs.length} attrs=${countAnnounceAttributes(payload)}${changedDetail}`;
+  }
+
+  function logAnnounce(
+    direction: "Sent" | "Received",
+    peerId: string,
+    payload: InstanceAnnouncePayload,
+    changed?: boolean,
+  ): void {
+    if (announceLogDetail === "off") {
+      if (direction === "Sent") {
+        logger?.info?.(
+          `[libp2p-mesh] Sent instance announce to ${peerId} (${payload.instanceId})`,
+        );
+      }
+      return;
+    }
+
+    logger?.info?.(announceSummary(direction, peerId, payload, changed));
+    if (announceLogDetail !== "payload") {
+      return;
+    }
+
+    try {
+      logger?.debug?.(
+        `[libp2p-mesh] ${direction} instance announce payload=${JSON.stringify(payload)}`,
+      );
+    } catch {
+      return;
+    }
   }
 
   async function announceToConnectedPeers(): Promise<void> {
@@ -255,9 +308,8 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
       logger?.info?.(
         `[libp2p-mesh] Instance mapping updated: ${payload.instanceId} -> ${payload.peerId}`,
       );
-    } else {
-      logger?.debug?.(`[libp2p-mesh] Instance mapping unchanged: ${payload.instanceId}`);
     }
+    logAnnounce("Received", msg.from, payload, result.changed);
 
     if (!announcedPeers.has(msg.from)) {
       await announceToPeer(msg.from).catch((error) => {
@@ -449,7 +501,11 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
     }
   }
 
-  async function start(): Promise<void> {
+  function attachHandlers(): void {
+    if (unsubs.length > 0) {
+      return;
+    }
+
     unsubs.push(
       mesh.onMessage((msg) => {
         handleMessage(msg).catch((error) => {
@@ -468,7 +524,10 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
         });
       }),
     );
+  }
 
+  async function start(): Promise<void> {
+    attachHandlers();
     await announceToConnectedPeers();
   }
 
@@ -658,6 +717,8 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
   }
 
   return {
+    attachHandlers,
+    announceToConnectedPeers,
     start,
     stop,
     handleMessage,

package/src/plugin.ts

@@ -12,13 +12,26 @@ import { registerLibp2pMeshCli } from "./profile-cli.js";
 import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
 import type { MeshConfig } from "./types.js";
 
+export type Libp2pMeshPluginDeps = {
+  createMeshNetwork?: typeof createMeshNetwork;
+  createInstanceRouter?: typeof createInstanceRouter;
+};
+
 export function registerLibp2pMesh(api: OpenClawPluginApi) {
+  registerLibp2pMeshWithDeps(api);
+}
+
+export function registerLibp2pMeshWithDeps(
+  api: OpenClawPluginApi,
+  deps: Libp2pMeshPluginDeps = {},
+) {
   registerLibp2pMeshCli(api);
 
   const config = api.pluginConfig as MeshConfig | undefined;
   let unsubscribeInbound: (() => void) | undefined;
   let serviceStarted = false;
-  const mesh = createMeshNetwork({
+  let startPromise: Promise<void> | undefined;
+  const mesh = (deps.createMeshNetwork ?? createMeshNetwork)({
     config,
     logger: api.logger,
   });
@@ -39,7 +52,7 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
     },
     logger: api.logger,
   });
-  const router = createInstanceRouter({
+  const router = (deps.createInstanceRouter ?? createInstanceRouter)({
     mesh,
     store,
     delivery,
@@ -51,6 +64,73 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
 
   const channel = createLibp2pMeshChannel(mesh);
 
+  function attachInboundHandlers(): () => void {
+    return mesh.onMessage((msg) => {
+      if (msg.type === "direct" || msg.type === "broadcast") {
+        const sendToChannel: InboundHandlerDeps["sendToChannel"] = async (_channelId, _target, text) => {
+          if (!config?.inboundChannel || !config?.inboundTarget) {
+            api.logger.warn?.(
+              "[libp2p-mesh] inboundChannel/inboundTarget not configured; direct message logged only.",
+            );
+            return;
+          }
+
+          const result = await delivery.deliver({
+            channel: config.inboundChannel,
+            target: config.inboundTarget,
+            text,
+            metadata: {
+              fromInstanceId: msg.instanceId ?? msg.from,
+              fromPeerId: msg.from,
+              p2pMessageId: msg.id,
+              allowAgentAutoReply: false,
+              replyToInstanceId: msg.instanceId ?? msg.from,
+              replyTool: "p2p_send_instance_message",
+            },
+          });
+          if (!result.ok) {
+            api.logger.error?.(
+              `[libp2p-mesh] Failed to forward direct message from ${msg.from}: ${result.error}`,
+            );
+          }
+        };
+        handleP2PInbound(msg, { logger: api.logger, sendToChannel });
+      } else if (msg.type === "agent-sync") {
+        handleP2PInbound(msg, { logger: api.logger });
+      }
+    });
+  }
+
+  async function cleanupStartupFailure(): Promise<void> {
+    try {
+      unsubscribeInbound?.();
+    } catch (error) {
+      api.logger.warn?.(
+        `[libp2p-mesh] Failed to clean inbound handler after startup failure: ${String(error)}`,
+      );
+    } finally {
+      unsubscribeInbound = undefined;
+    }
+
+    try {
+      await router.stop();
+    } catch (error) {
+      api.logger.warn?.(
+        `[libp2p-mesh] Failed to stop router after startup failure: ${String(error)}`,
+      );
+    }
+
+    try {
+      await mesh.stop();
+    } catch (error) {
+      api.logger.warn?.(
+        `[libp2p-mesh] Failed to stop mesh after startup failure: ${String(error)}`,
+      );
+    }
+
+    serviceStarted = false;
+  }
+
   // 1. Register Service (manages libp2p node lifecycle)
   api.registerService({
     id: "libp2p-mesh",
@@ -59,64 +139,52 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
         api.logger.debug?.("[libp2p-mesh] Service already started; ignoring duplicate start.");
         return;
       }
-      await mesh.start();
-      await router.start();
-      unsubscribeInbound = mesh.onMessage((msg) => {
-        if (msg.type === "direct" || msg.type === "broadcast") {
-          const sendToChannel: InboundHandlerDeps["sendToChannel"] = async (_channelId, _target, text) => {
-            if (!config?.inboundChannel || !config?.inboundTarget) {
-              api.logger.warn?.(
-                "[libp2p-mesh] inboundChannel/inboundTarget not configured; direct message logged only.",
-              );
-              return;
-            }
-
-            const result = await delivery.deliver({
-              channel: config.inboundChannel,
-              target: config.inboundTarget,
-              text,
-              metadata: {
-                fromInstanceId: msg.instanceId ?? msg.from,
-                fromPeerId: msg.from,
-                p2pMessageId: msg.id,
-                allowAgentAutoReply: false,
-                replyToInstanceId: msg.instanceId ?? msg.from,
-                replyTool: "p2p_send_instance_message",
-              },
-            });
-            if (!result.ok) {
-              api.logger.error?.(
-                `[libp2p-mesh] Failed to forward direct message from ${msg.from}: ${result.error}`,
-              );
-            }
-          };
-          handleP2PInbound(msg, { logger: api.logger, sendToChannel });
-        } else if (msg.type === "agent-sync") {
-          handleP2PInbound(msg, { logger: api.logger });
-        }
-      });
-      const identity = mesh.getInstanceIdentity();
-      api.logger.info?.(`[libp2p-mesh] Service started. Peer ID: ${mesh.getLocalPeerId()}`);
-      if (identity) {
-        api.logger.info?.(`[libp2p-mesh] Instance Identity: ${identity.id}`);
-      }
-      const nat = mesh.getNATStatus();
-      const enabledNames = Object.entries(nat.enabled)
-        .filter(([, on]) => on)
-        .map(([k]) => k);
-      if (enabledNames.length > 0) {
-        api.logger.info?.(
-          `[libp2p-mesh] NAT traversal services: ${enabledNames.join(", ")}`,
-        );
-      }
-      if (nat.reservedRelays.length > 0) {
-        api.logger.info?.(
-          `[libp2p-mesh] Active relay reservations: ${nat.reservedRelays.join(", ")}`,
-        );
+
+      if (startPromise) {
+        api.logger.debug?.("[libp2p-mesh] Service start already in progress; waiting for it.");
+        return startPromise;
       }
-      serviceStarted = true;
+
+      startPromise = (async () => {
+        try {
+          router.attachHandlers();
+          unsubscribeInbound = attachInboundHandlers();
+          await mesh.start();
+          await router.announceToConnectedPeers();
+          const identity = mesh.getInstanceIdentity();
+          api.logger.info?.(
+            `[libp2p-mesh] Service started. Peer ID: ${mesh.getLocalPeerId()}`,
+          );
+          if (identity) {
+            api.logger.info?.(`[libp2p-mesh] Instance Identity: ${identity.id}`);
+          }
+          const nat = mesh.getNATStatus();
+          const enabledNames = Object.entries(nat.enabled)
+            .filter(([, on]) => on)
+            .map(([k]) => k);
+          if (enabledNames.length > 0) {
+            api.logger.info?.(
+              `[libp2p-mesh] NAT traversal services: ${enabledNames.join(", ")}`,
+            );
+          }
+          if (nat.reservedRelays.length > 0) {
+            api.logger.info?.(
+              `[libp2p-mesh] Active relay reservations: ${nat.reservedRelays.join(", ")}`,
+            );
+          }
+          serviceStarted = true;
+        } catch (error) {
+          await cleanupStartupFailure();
+          throw error;
+        } finally {
+          startPromise = undefined;
+        }
+      })();
+
+      return startPromise;
     },
     stop: async () => {
+      await startPromise?.catch(() => undefined);
       unsubscribeInbound?.();
       unsubscribeInbound = undefined;
       await router.stop();

package/src/profile-cli.ts

@@ -7,6 +7,7 @@ import {
   type ClosableSetupPrompter,
   type SetupCliDeps,
 } from "./setup-cli.js";
+import { registerLibp2pMeshDebugCommand, type DebugCliDeps } from "./debug-cli.js";
 import { runProfileWizard } from "./profile-wizard.js";
 import { createUserMdAttributeSource } from "./user-md-attributes.js";
 import { createUserProfileStore, type UserProfileStore } from "./user-profile-store.js";
@@ -29,6 +30,7 @@ export type ProfileCliDeps = {
 export type Libp2pMeshCliDeps = {
   setup?: SetupCliDeps;
   profile?: ProfileCliDeps;
+  debug?: DebugCliDeps;
 };
 
 export function registerLibp2pMeshCli(api: OpenClawPluginApi, deps: Libp2pMeshCliDeps = {}): void {
@@ -39,6 +41,7 @@ export function registerLibp2pMeshCli(api: OpenClawPluginApi, deps: Libp2pMeshCl
 
     registerLibp2pMeshSetupCommand(root, api, ctx, deps.setup);
     registerLibp2pMeshProfileCommand(root, api, ctx, deps.profile);
+    registerLibp2pMeshDebugCommand(root, api, ctx, deps.debug);
   }, LIBP2P_MESH_CLI_REGISTRATION);
 }
 

package/src/setup-config.ts

@@ -1,4 +1,4 @@
-import type { InboundTargetConfig, MeshConfig } from "./types.js";
+import type { AnnounceLogDetail, InboundTargetConfig, MeshConfig } from "./types.js";
 
 export const LIBP2P_MESH_PLUGIN_ID = "libp2p-mesh";
 export const DEFAULT_DELIVERY_ACK_TIMEOUT_MS = 15000;
@@ -38,6 +38,14 @@ export function getLibp2pMeshConfig(config: OpenClawConfigLike): MeshConfig | un
   return config.plugins?.entries?.[LIBP2P_MESH_PLUGIN_ID]?.config as MeshConfig | undefined;
 }
 
+export function getAnnounceLogDetail(config: OpenClawConfigLike): AnnounceLogDetail {
+  return normalizeAnnounceLogDetail(getLibp2pMeshConfig(config)?.announceLogDetail);
+}
+
+export function normalizeAnnounceLogDetail(value: unknown): AnnounceLogDetail {
+  return value === "off" || value === "payload" || value === "summary" ? value : "summary";
+}
+
 export function buildNetworkConfig(
   mode: SetupMode,
   options?: {
@@ -99,6 +107,32 @@ export function applyPluginConfig(config: OpenClawConfigLike, pluginConfig: Mesh
   };
 }
 
+export function applyAnnounceLogDetail(
+  config: OpenClawConfigLike,
+  announceLogDetail: AnnounceLogDetail,
+): OpenClawConfigLike {
+  const existingEntry = config.plugins?.entries?.[LIBP2P_MESH_PLUGIN_ID];
+  const existingPluginConfig = existingEntry?.config ?? {};
+
+  return {
+    ...config,
+    plugins: {
+      ...config.plugins,
+      entries: {
+        ...config.plugins?.entries,
+        [LIBP2P_MESH_PLUGIN_ID]: {
+          ...existingEntry,
+          enabled: existingEntry?.enabled ?? true,
+          config: {
+            ...existingPluginConfig,
+            announceLogDetail,
+          },
+        },
+      },
+    },
+  };
+}
+
 export function mergeNetworkConfig(existing: MeshConfig | undefined, networkConfig: MeshConfig): MeshConfig {
   if (!existing) {
     return { ...networkConfig };

package/src/types.ts

@@ -203,6 +203,8 @@ export type InstanceRouterOptions = {
 };
 
 export interface InstanceRouter {
+  attachHandlers(): void;
+  announceToConnectedPeers(): Promise<void>;
   start(): Promise<void>;
   stop(): Promise<void>;
   handleMessage(msg: P2PMessage): Promise<void>;
@@ -232,6 +234,7 @@ export interface MeshConfig {
   discovery?: "mdns" | "bootstrap" | "dht";
   bootstrapList?: string[];
   meshTopic?: string;
+  announceLogDetail?: AnnounceLogDetail;
   enableAgentSync?: boolean;
   enableWebSocket?: boolean;
   peerIdPath?: string;
@@ -335,6 +338,8 @@ export interface MeshNetwork {
   getNATStatus(): NATTraversalStatus;
 }
 
+export type AnnounceLogDetail = "off" | "summary" | "payload";
+
 export type MeshAccount = {
   accountId: string;
   configured: boolean;

package/src/user-md-attributes.ts

@@ -1,4 +1,5 @@
 import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import path from "node:path";
 
 import type { UserPublicAttribute } from "./types.js";
@@ -59,6 +60,19 @@ export type UserMdAttributeSource = {
   };
 };
 
+export function resolveUserMdPath(customPath?: string): string {
+  if (customPath) {
+    return customPath;
+  }
+
+  const stateDir = process.env.OPENCLAW_STATE_DIR;
+  if (stateDir) {
+    return path.join(stateDir, "workspace", "USER.md");
+  }
+
+  return path.join(homedir(), ".openclaw", "workspace", "USER.md");
+}
+
 function isTemplateText(value: string): boolean {
   const trimmed = value.trim();
   return trimmed.length === 0 || TEMPLATE_PATTERN.test(trimmed) || /^\[[^\]]+\]$/.test(trimmed);
@@ -236,7 +250,7 @@ export function extractUserMdTags(markdown: string): UserPublicAttribute[] {
 export function createUserMdAttributeSource(options?: UserMdAttributeSource): {
   loadTags(): Promise<UserPublicAttribute[]>;
 } {
-  const filePath = options?.path ?? path.join(process.cwd(), "USER.md");
+  const filePath = resolveUserMdPath(options?.path);
   const logger = options?.logger;
 
   return {