libp2p-mesh 2026.6.11 → 2026.6.13

package/src/profile-wizard.ts

@@ -0,0 +1,204 @@
+import { SetupCancelledError, type SetupPrompter } from "./setup-wizard.js";
+import type { UserPublicAttribute } from "./types.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 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 };
+
+type ProfileAction =
+  | "add-attribute"
+  | "edit-attribute"
+  | "remove-attribute"
+  | "preview-finish"
+  | "cancel";
+
+export async function runProfileWizard(options: RunProfileWizardOptions): Promise<ProfileWizardResult> {
+  try {
+    const readOnlyTags = options.readOnlyTags
+      .map((attribute) => normalizeUserPublicAttribute(attribute))
+      .filter((attribute): attribute is UserPublicAttribute => attribute?.kind === "tag");
+    let attributes = normalizeProfileAttributes(options.profileAttributes);
+
+    options.prompter.print(formatProfileOverview(readOnlyTags, attributes));
+
+    while (true) {
+      const action = await options.prompter.select<ProfileAction>("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: UserPublicAttribute[]): UserPublicAttribute[] {
+  return mergeUserPublicAttributes([], attributes).filter(
+    (attribute): attribute is UserPublicAttribute & { kind: "structured" } => attribute.kind === "structured",
+  );
+}
+
+async function promptForAttribute(prompter: SetupPrompter): Promise<UserPublicAttribute> {
+  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: SetupPrompter,
+  attributes: UserPublicAttribute[],
+): Promise<UserPublicAttribute[]> {
+  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: SetupPrompter,
+  attributes: UserPublicAttribute[],
+): Promise<UserPublicAttribute[]> {
+  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: SetupPrompter,
+  message: string,
+  attributes: UserPublicAttribute[],
+): Promise<number> {
+  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: UserPublicAttribute[], attributes: UserPublicAttribute[]): string {
+  return [
+    "Read-only USER.md tags:",
+    ...formatAttributeList(readOnlyTags),
+    "",
+    "Structured profile attributes:",
+    ...formatAttributeList(attributes),
+  ].join("\n");
+}
+
+function formatProfilePreview(readOnlyTags: UserPublicAttribute[], attributes: UserPublicAttribute[]): string {
+  return [
+    "Preview: public attributes",
+    "",
+    "Read-only USER.md tags:",
+    ...formatAttributeList(readOnlyTags),
+    "",
+    "Structured profile attributes to save:",
+    ...formatAttributeList(attributes),
+  ].join("\n");
+}
+
+function formatAttributeList(attributes: UserPublicAttribute[]): string[] {
+  if (attributes.length === 0) {
+    return ["  none"];
+  }
+  return attributes.map((attribute, index) => `  ${index + 1}. ${formatAttribute(attribute)}`);
+}
+
+function formatAttribute(attribute: UserPublicAttribute): string {
+  if (attribute.kind === "tag") {
+    return `${attribute.label} (USER.md tag, read-only)`;
+  }
+  return `${attribute.key}: ${attribute.value}`;
+}
+
+function cancelledResult(): ProfileWizardResult {
+  return {
+    status: "cancelled",
+    message: CANCELLED_MESSAGE,
+  };
+}

package/src/setup-cli.ts

@@ -16,7 +16,18 @@ const SETUP_CLI_AFTER_WRITE = {
   reason: "libp2p-mesh setup completed; restart manually to apply gateway changes.",
 } as const;
 
-type ClosableSetupPrompter = SetupPrompter & {
+export const LIBP2P_MESH_CLI_REGISTRATION = {
+  commands: ["libp2p-mesh"],
+  descriptors: [
+    {
+      name: "libp2p-mesh",
+      description: "Configure libp2p-mesh plugin.",
+      hasSubcommands: true,
+    },
+  ],
+};
+
+export type ClosableSetupPrompter = SetupPrompter & {
   close?: () => void;
 };
 
@@ -32,37 +43,37 @@ export function registerLibp2pMeshSetupCli(api: OpenClawPluginApi, deps: SetupCl
         .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()) as ClosableSetupPrompter;
-          const writer = deps.createWriter?.(api) ?? createOpenClawConfigWriter(api);
-          try {
-            const result = await runSetupWizard({
-              currentConfig: ctx.config as OpenClawConfigLike,
-              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: { command(name: string): { description(text: string): { action(handler: () => Promise<void>): void } } },
+  api: OpenClawPluginApi,
+  ctx: OpenClawPluginCliContext,
+  deps: SetupCliDeps = {},
+): void {
+  root
+    .command("setup")
+    .description("Run the libp2p-mesh setup wizard.")
+    .action(async () => {
+      const prompter = (deps.createPrompter?.(ctx) ?? createReadlinePrompter()) as ClosableSetupPrompter;
+      const writer = deps.createWriter?.(api) ?? createOpenClawConfigWriter(api);
+      try {
+        const result = await runSetupWizard({
+          currentConfig: ctx.config as OpenClawConfigLike,
+          prompter,
+          writer,
+        });
+        prompter.print(result.message);
+      } finally {
+        prompter.close?.();
+      }
+    });
+}
+
 function createOpenClawConfigWriter(api: OpenClawPluginApi): SetupConfigWriter {
   return {
     async write(nextConfig) {
@@ -83,7 +94,7 @@ function replaceConfig(draft: OpenClawConfig, nextConfig: OpenClawConfig): void
   Object.assign(draft, structuredClone(nextConfig));
 }
 
-function createReadlinePrompter(): ClosableSetupPrompter {
+export function createReadlinePrompter(): ClosableSetupPrompter {
   const readline = createInterface({ input, output });
 
   return {

package/src/types.ts

@@ -47,6 +47,7 @@ export interface InstanceAnnouncePayload {
   instanceName?: string;
   multiaddrs: string[];
   pubkey?: string;
+  userPublicAttributes?: UserPublicAttribute[];
   announcedAt: number;
 }
 
@@ -86,12 +87,32 @@ export interface DeliveryAckPayload {
   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";
@@ -114,6 +135,29 @@ export interface InstancePeerStore {
   }>;
 }
 
+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;
@@ -139,6 +183,25 @@ 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>;
@@ -157,6 +220,11 @@ export interface InstanceRouter {
     deliveryResults?: DeliveryTargetResult[];
     error?: string;
   }>;
+  sendUserAttributeMessage(
+    match: UserAttributeMatch,
+    message: string,
+    options?: { dryRun?: boolean },
+  ): Promise<UserAttributeMessageResult>;
 }
 
 export interface MeshConfig {

package/src/user-attributes.ts

@@ -0,0 +1,122 @@
+import type { UserAttributeMatch, UserPublicAttribute } from "./types.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function trimmedString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+export function normalizeAttributeValue(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+export function normalizeAttributeKey(key: string): string {
+  return key.trim().toLowerCase();
+}
+
+export function normalizeUserPublicAttribute(value: unknown): UserPublicAttribute | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+
+  if (value.kind === "tag") {
+    if (value.source !== "USER.md") {
+      return undefined;
+    }
+
+    const attributeValue = trimmedString(value.value);
+    const label = trimmedString(value.label);
+    if (!attributeValue || !label) {
+      return undefined;
+    }
+
+    return {
+      kind: "tag",
+      value: attributeValue,
+      label,
+      source: "USER.md",
+    };
+  }
+
+  if (value.kind === "structured") {
+    if (value.source !== "profile") {
+      return undefined;
+    }
+
+    const key = trimmedString(value.key);
+    const attributeValue = trimmedString(value.value);
+    const label = trimmedString(value.label);
+    if (!key || !attributeValue || !label) {
+      return undefined;
+    }
+
+    return {
+      kind: "structured",
+      key: normalizeAttributeKey(key),
+      value: attributeValue,
+      label,
+      source: "profile",
+    };
+  }
+
+  return undefined;
+}
+
+function attributeDedupeKey(attribute: UserPublicAttribute): string {
+  if (attribute.kind === "tag") {
+    return `tag:${normalizeAttributeValue(attribute.value)}`;
+  }
+
+  return `structured:${normalizeAttributeKey(attribute.key)}:${normalizeAttributeValue(attribute.value)}`;
+}
+
+export function mergeUserPublicAttributes(
+  userMdTags: UserPublicAttribute[],
+  profileAttributes: UserPublicAttribute[],
+): UserPublicAttribute[] {
+  const merged: UserPublicAttribute[] = [];
+  const seen = new Set<string>();
+
+  for (const rawAttribute of [...userMdTags, ...profileAttributes]) {
+    const attribute = normalizeUserPublicAttribute(rawAttribute);
+    if (!attribute) {
+      continue;
+    }
+
+    const key = attributeDedupeKey(attribute);
+    if (seen.has(key)) {
+      continue;
+    }
+
+    seen.add(key);
+    merged.push(attribute);
+  }
+
+  return merged;
+}
+
+export function matchesUserAttribute(attribute: UserPublicAttribute, match: UserAttributeMatch): boolean {
+  if (attribute.kind !== match.kind) {
+    return false;
+  }
+
+  if (attribute.kind === "tag") {
+    return normalizeAttributeValue(attribute.value) === normalizeAttributeValue(match.value);
+  }
+
+  if (match.kind !== "structured") {
+    return false;
+  }
+
+  return (
+    normalizeAttributeKey(attribute.key) === normalizeAttributeKey(match.key) &&
+    normalizeAttributeValue(attribute.value) === normalizeAttributeValue(match.value)
+  );
+}