clawdentity 0.0.17 → 0.0.18

package/dist/bin.js

@@ -17084,7 +17084,8 @@ var FILE_MODE = 384;
 var ENV_KEY_MAP = {
   registryUrl: "CLAWDENTITY_REGISTRY_URL",
   proxyUrl: "CLAWDENTITY_PROXY_URL",
-  apiKey: "CLAWDENTITY_API_KEY"
+  apiKey: "CLAWDENTITY_API_KEY",
+  humanName: "CLAWDENTITY_HUMAN_NAME"
 };
 var LEGACY_ENV_KEY_MAP = {
   registryUrl: ["CLAWDENTITY_REGISTRY"]
@@ -17111,6 +17112,9 @@ var normalizeConfig = (raw) => {
   if (typeof raw.apiKey === "string" && raw.apiKey.length > 0) {
     config2.apiKey = raw.apiKey;
   }
+  if (typeof raw.humanName === "string" && raw.humanName.length > 0) {
+    config2.humanName = raw.humanName;
+  }
   return config2;
 };
 var getConfigDir = () => join2(homedir(), CONFIG_DIR);
@@ -18536,7 +18540,8 @@ var logger5 = createLogger({ service: "cli", module: "config" });
 var VALID_KEYS = [
   "registryUrl",
   "proxyUrl",
-  "apiKey"
+  "apiKey",
+  "humanName"
 ];
 var isValidConfigKey = (value) => {
   return VALID_KEYS.includes(value);
@@ -20862,11 +20867,20 @@ function parseInviteRedeemResponse(payload) {
   }
   const apiKeyId = parseNonEmptyString7(apiKeySource.id);
   const apiKeyName = parseNonEmptyString7(apiKeySource.name);
+  const humanSource = isRecord7(payload.human) ? payload.human : void 0;
+  const humanName = parseNonEmptyString7(humanSource?.displayName);
   const proxyUrl = parseNonEmptyString7(payload.proxyUrl);
+  if (humanName.length === 0) {
+    throw createCliError5(
+      "CLI_INVITE_REDEEM_INVALID_RESPONSE",
+      "Invite redeem response is invalid"
+    );
+  }
   return {
     apiKeyToken,
     apiKeyId: apiKeyId.length > 0 ? apiKeyId : void 0,
     apiKeyName: apiKeyName.length > 0 ? apiKeyName : void 0,
+    humanName,
     proxyUrl
   };
 }
@@ -20921,6 +20935,14 @@ async function redeemInvite(code, options, dependencies = {}) {
       "Invite code is required"
     );
   }
+  const displayName = parseNonEmptyString7(options.displayName);
+  if (displayName.length === 0) {
+    throw createCliError5(
+      "CLI_INVITE_REDEEM_DISPLAY_NAME_REQUIRED",
+      "Display name is required. Pass --display-name <name>."
+    );
+  }
+  const apiKeyName = parseNonEmptyString7(options.apiKeyName);
   const runtime = await resolveInviteRuntime(options.registryUrl, dependencies);
   const response = await executeInviteRequest({
     fetchImpl: runtime.fetchImpl,
@@ -20930,7 +20952,11 @@ async function redeemInvite(code, options, dependencies = {}) {
       headers: {
         "content-type": "application/json"
       },
-      body: JSON.stringify({ code: inviteCode })
+      body: JSON.stringify({
+        code: inviteCode,
+        displayName,
+        apiKeyName: apiKeyName.length > 0 ? apiKeyName : void 0
+      })
     }
   });
   const responseBody = await parseJsonResponse5(response);
@@ -20950,12 +20976,13 @@ async function redeemInvite(code, options, dependencies = {}) {
     registryUrl: runtime.registryUrl
   };
 }
-async function persistRedeemConfig(registryUrl, apiKeyToken, proxyUrl, dependencies = {}) {
+async function persistRedeemConfig(registryUrl, apiKeyToken, proxyUrl, humanName, dependencies = {}) {
   const setConfigValueImpl = dependencies.setConfigValueImpl ?? setConfigValue;
   try {
     await setConfigValueImpl("registryUrl", registryUrl);
     await setConfigValueImpl("apiKey", apiKeyToken);
     await setConfigValueImpl("proxyUrl", proxyUrl);
+    await setConfigValueImpl("humanName", humanName);
   } catch (error48) {
     logger7.warn("cli.invite_redeem_config_persist_failed", {
       errorName: error48 instanceof Error ? error48.name : "unknown"
@@ -20989,7 +21016,10 @@ var createInviteCommand = (dependencies = {}) => {
       }
     )
   );
-  inviteCommand.command("redeem <code>").description("Redeem a registry invite code and store PAT locally").option("--registry-url <url>", "Override registry URL").action(
+  inviteCommand.command("redeem <code>").description("Redeem a registry invite code and store PAT locally").requiredOption(
+    "--display-name <name>",
+    "Human display name used for onboarding"
+  ).option("--api-key-name <name>", "Optional API key label").option("--registry-url <url>", "Override registry URL").action(
     withErrorHandling(
       "invite redeem",
       async (code, options) => {
@@ -20997,9 +21027,11 @@ var createInviteCommand = (dependencies = {}) => {
         logger7.info("cli.invite_redeemed", {
           apiKeyId: result.apiKeyId,
           apiKeyName: result.apiKeyName,
+          humanName: result.humanName,
           registryUrl: result.registryUrl
         });
         writeStdoutLine("Invite redeemed");
+        writeStdoutLine(`Human name: ${result.humanName}`);
         if (result.apiKeyName) {
           writeStdoutLine(`API key name: ${result.apiKeyName}`);
         }
@@ -21009,6 +21041,7 @@ var createInviteCommand = (dependencies = {}) => {
           result.registryUrl,
           result.apiKeyToken,
           result.proxyUrl,
+          result.humanName,
           dependencies
         );
         writeStdoutLine("API key saved to local config");
@@ -21113,11 +21146,11 @@ function parseNonEmptyString8(value, label) {
   }
   return trimmed;
 }
-function parseOptionalName(value) {
+function parseOptionalProfileName(value, label) {
   if (value === void 0) {
     return void 0;
   }
-  return parseNonEmptyString8(value, "name");
+  return parseNonEmptyString8(value, label);
 }
 function parsePeerAlias(value) {
   const alias = parseNonEmptyString8(value, "peer alias");
@@ -21374,12 +21407,13 @@ async function loadPeersConfig(peersPath) {
     }
     const did = parseAgentDid2(value.did, `Peer ${normalizedAlias} did`);
     const proxyUrl = parseProxyUrl(value.proxyUrl);
-    const name = parseOptionalName(value.name);
-    if (name === void 0) {
+    const agentName = parseOptionalProfileName(value.agentName, "agentName");
+    const humanName = parseOptionalProfileName(value.humanName, "humanName");
+    if (agentName === void 0 && humanName === void 0) {
       peers[normalizedAlias] = { did, proxyUrl };
       continue;
     }
-    peers[normalizedAlias] = { did, proxyUrl, name };
+    peers[normalizedAlias] = { did, proxyUrl, agentName, humanName };
   }
   return { peers };
 }
@@ -22978,6 +23012,7 @@ var FILE_MODE4 = 384;
 var PEER_ALIAS_PATTERN2 = /^[a-zA-Z0-9._-]+$/;
 var DEFAULT_STATUS_WAIT_SECONDS = 300;
 var DEFAULT_STATUS_POLL_INTERVAL_SECONDS = 3;
+var MAX_PROFILE_NAME_LENGTH = 64;
 var isRecord9 = (value) => {
   return typeof value === "object" && value !== null;
 };
@@ -22994,6 +23029,49 @@ function parseNonEmptyString9(value) {
   }
   return value.trim();
 }
+function hasControlChars2(value) {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code <= 31 || code === 127) {
+      return true;
+    }
+  }
+  return false;
+}
+function parseProfileName(value, label) {
+  const candidate = parseNonEmptyString9(value);
+  if (candidate.length === 0) {
+    throw createCliError7(
+      "CLI_PAIR_PROFILE_INVALID",
+      `${label} is required for pairing`
+    );
+  }
+  if (candidate.length > MAX_PROFILE_NAME_LENGTH) {
+    throw createCliError7(
+      "CLI_PAIR_PROFILE_INVALID",
+      `${label} must be at most ${MAX_PROFILE_NAME_LENGTH} characters`
+    );
+  }
+  if (hasControlChars2(candidate)) {
+    throw createCliError7(
+      "CLI_PAIR_PROFILE_INVALID",
+      `${label} contains control characters`
+    );
+  }
+  return candidate;
+}
+function parsePeerProfile(payload) {
+  if (!isRecord9(payload)) {
+    throw createCliError7(
+      "CLI_PAIR_PROFILE_INVALID",
+      "Pair profile must be an object"
+    );
+  }
+  return {
+    agentName: parseProfileName(payload.agentName, "agentName"),
+    humanName: parseProfileName(payload.humanName, "humanName")
+  };
+}
 function parsePairingTicket(value) {
   const ticket = parseNonEmptyString9(value);
   if (!ticket.startsWith(PAIRING_TICKET_PREFIX)) {
@@ -23158,10 +23236,19 @@ function parsePeerEntry(value) {
       "Peer entry is invalid"
     );
   }
-  return {
+  const agentNameRaw = parseNonEmptyString9(value.agentName);
+  const humanNameRaw = parseNonEmptyString9(value.humanName);
+  const entry = {
     did,
     proxyUrl
   };
+  if (agentNameRaw.length > 0) {
+    entry.agentName = parseProfileName(agentNameRaw, "agentName");
+  }
+  if (humanNameRaw.length > 0) {
+    entry.humanName = parseProfileName(humanNameRaw, "humanName");
+  }
+  return entry;
 }
 async function loadPeersConfig2(input) {
   const peersPath = resolvePeersConfigPath(input.getConfigDirImpl);
@@ -23244,6 +23331,19 @@ function parsePositiveIntegerOption(input) {
   }
   return parsed;
 }
+function resolveLocalPairProfile(input) {
+  const humanName = parseNonEmptyString9(input.config.humanName);
+  if (humanName.length === 0) {
+    throw createCliError7(
+      "CLI_PAIR_HUMAN_NAME_MISSING",
+      "Human name is missing. Run `clawdentity invite redeem <clw_inv_...> --display-name <name>` or `clawdentity config set humanName <name>`."
+    );
+  }
+  return {
+    agentName: parseProfileName(input.agentName, "agentName"),
+    humanName: parseProfileName(humanName, "humanName")
+  };
+}
 function parseProxyUrl2(candidate) {
   try {
     const parsed = new URL(candidate);
@@ -23394,15 +23494,25 @@ function parsePairStartResponse(payload) {
   const ticket = parsePairingTicket(payload.ticket);
   const initiatorAgentDid = parseNonEmptyString9(payload.initiatorAgentDid);
   const expiresAt = parseNonEmptyString9(payload.expiresAt);
+  let initiatorProfile;
   if (initiatorAgentDid.length === 0 || expiresAt.length === 0) {
     throw createCliError7(
       "CLI_PAIR_START_INVALID_RESPONSE",
       "Pair start response is invalid"
     );
   }
+  try {
+    initiatorProfile = parsePeerProfile(payload.initiatorProfile);
+  } catch {
+    throw createCliError7(
+      "CLI_PAIR_START_INVALID_RESPONSE",
+      "Pair start response is invalid"
+    );
+  }
   return {
     ticket,
     initiatorAgentDid,
+    initiatorProfile,
     expiresAt
   };
 }
@@ -23416,16 +23526,29 @@ function parsePairConfirmResponse(payload) {
   const paired = payload.paired === true;
   const initiatorAgentDid = parseNonEmptyString9(payload.initiatorAgentDid);
   const responderAgentDid = parseNonEmptyString9(payload.responderAgentDid);
+  let initiatorProfile;
+  let responderProfile;
   if (!paired || initiatorAgentDid.length === 0 || responderAgentDid.length === 0) {
     throw createCliError7(
       "CLI_PAIR_CONFIRM_INVALID_RESPONSE",
       "Pair confirm response is invalid"
     );
   }
+  try {
+    initiatorProfile = parsePeerProfile(payload.initiatorProfile);
+    responderProfile = parsePeerProfile(payload.responderProfile);
+  } catch {
+    throw createCliError7(
+      "CLI_PAIR_CONFIRM_INVALID_RESPONSE",
+      "Pair confirm response is invalid"
+    );
+  }
   return {
     paired,
     initiatorAgentDid,
-    responderAgentDid
+    responderAgentDid,
+    initiatorProfile,
+    responderProfile
   };
 }
 function parsePairStatusResponse(payload) {
@@ -23446,6 +23569,7 @@ function parsePairStatusResponse(payload) {
   const responderAgentDid = parseNonEmptyString9(payload.responderAgentDid);
   const expiresAt = parseNonEmptyString9(payload.expiresAt);
   const confirmedAt = parseNonEmptyString9(payload.confirmedAt);
+  let initiatorProfile;
   if (initiatorAgentDid.length === 0 || expiresAt.length === 0) {
     throw createCliError7(
       "CLI_PAIR_STATUS_INVALID_RESPONSE",
@@ -23458,10 +23582,37 @@ function parsePairStatusResponse(payload) {
       "Pair status response is invalid"
     );
   }
+  try {
+    initiatorProfile = parsePeerProfile(payload.initiatorProfile);
+  } catch {
+    throw createCliError7(
+      "CLI_PAIR_STATUS_INVALID_RESPONSE",
+      "Pair status response is invalid"
+    );
+  }
+  let responderProfile;
+  if (payload.responderProfile !== void 0) {
+    try {
+      responderProfile = parsePeerProfile(payload.responderProfile);
+    } catch {
+      throw createCliError7(
+        "CLI_PAIR_STATUS_INVALID_RESPONSE",
+        "Pair status response is invalid"
+      );
+    }
+  }
+  if (statusRaw === "confirmed" && responderProfile === void 0) {
+    throw createCliError7(
+      "CLI_PAIR_STATUS_INVALID_RESPONSE",
+      "Pair status response is invalid"
+    );
+  }
   return {
     status: statusRaw,
     initiatorAgentDid,
+    initiatorProfile,
     responderAgentDid: responderAgentDid.length > 0 ? responderAgentDid : void 0,
+    responderProfile,
     expiresAt,
     confirmedAt: confirmedAt.length > 0 ? confirmedAt : void 0
   };
@@ -23666,7 +23817,9 @@ async function persistPairedPeer(input) {
   });
   peersConfig.peers[alias] = {
     did: input.peerDid,
-    proxyUrl: peerProxyUrl
+    proxyUrl: peerProxyUrl,
+    agentName: input.peerProfile.agentName,
+    humanName: input.peerProfile.humanName
   };
   await savePeersConfig2({
     config: peersConfig,
@@ -23688,13 +23841,19 @@ async function startPairing(agentName, options, dependencies = {}) {
     config: config2,
     fetchImpl
   });
+  const normalizedAgentName = assertValidAgentName(agentName);
+  const initiatorProfile = resolveLocalPairProfile({
+    config: config2,
+    agentName: normalizedAgentName
+  });
   const { ait, secretKey } = await readAgentProofMaterial(
-    agentName,
+    normalizedAgentName,
     dependencies
   );
   const requestUrl = toProxyRequestUrl(proxyUrl, PAIR_START_PATH);
   const requestBody = JSON.stringify({
-    ttlSeconds
+    ttlSeconds,
+    initiatorProfile
   });
   const bodyBytes = new TextEncoder().encode(requestBody);
   const timestampSeconds = nowSecondsImpl();
@@ -23751,6 +23910,11 @@ async function confirmPairing(agentName, options, dependencies = {}) {
   const readFileImpl = dependencies.readFileImpl ?? readFile6;
   const qrDecodeImpl = dependencies.qrDecodeImpl ?? decodeTicketFromPng;
   const config2 = await resolveConfigImpl();
+  const normalizedAgentName = assertValidAgentName(agentName);
+  const responderProfile = resolveLocalPairProfile({
+    config: config2,
+    agentName: normalizedAgentName
+  });
   const ticketSource = resolveConfirmTicketSource(options);
   const proxyUrl = await resolveProxyUrl({
     config: config2,
@@ -23780,11 +23944,14 @@ async function confirmPairing(agentName, options, dependencies = {}) {
     ticket = parsePairingTicket(qrDecodeImpl(new Uint8Array(imageBytes)));
   }
   const { ait, secretKey } = await readAgentProofMaterial(
-    agentName,
+    normalizedAgentName,
     dependencies
   );
   const requestUrl = toProxyRequestUrl(proxyUrl, PAIR_CONFIRM_PATH);
-  const requestBody = JSON.stringify({ ticket });
+  const requestBody = JSON.stringify({
+    ticket,
+    responderProfile
+  });
   const bodyBytes = new TextEncoder().encode(requestBody);
   const timestampSeconds = nowSecondsImpl();
   const nonce = nonceFactoryImpl();
@@ -23820,6 +23987,7 @@ async function confirmPairing(agentName, options, dependencies = {}) {
   const peerAlias = await persistPairedPeer({
     ticket,
     peerDid: parsed.initiatorAgentDid,
+    peerProfile: parsed.initiatorProfile,
     dependencies
   });
   if (ticketSource.source === "qr-file" && ticketSource.qrFilePath) {
@@ -23901,15 +24069,23 @@ async function getPairingStatusOnce(agentName, options, dependencies = {}) {
       );
     }
     const peerDid = callerAgentDid === parsed.initiatorAgentDid ? responderAgentDid : callerAgentDid === responderAgentDid ? parsed.initiatorAgentDid : void 0;
+    const peerProfile = callerAgentDid === parsed.initiatorAgentDid ? parsed.responderProfile : callerAgentDid === responderAgentDid ? parsed.initiatorProfile : void 0;
     if (!peerDid) {
       throw createCliError7(
         "CLI_PAIR_STATUS_FORBIDDEN",
         "Local agent is not a participant in the pairing ticket"
       );
     }
+    if (!peerProfile) {
+      throw createCliError7(
+        "CLI_PAIR_STATUS_INVALID_RESPONSE",
+        "Pair status response is invalid"
+      );
+    }
     peerAlias = await persistPairedPeer({
       ticket,
       peerDid,
+      peerProfile,
       dependencies
     });
   }
@@ -24005,6 +24181,12 @@ var createPairCommand = (dependencies = {}) => {
         writeStdoutLine("Pairing ticket created");
         writeStdoutLine(`Ticket: ${result.ticket}`);
         writeStdoutLine(`Initiator Agent DID: ${result.initiatorAgentDid}`);
+        writeStdoutLine(
+          `Initiator Agent Name: ${result.initiatorProfile.agentName}`
+        );
+        writeStdoutLine(
+          `Initiator Human Name: ${result.initiatorProfile.humanName}`
+        );
         writeStdoutLine(`Expires At: ${result.expiresAt}`);
         if (result.qrPath) {
           writeStdoutLine(`QR File: ${result.qrPath}`);
@@ -24047,6 +24229,14 @@ var createPairCommand = (dependencies = {}) => {
               `Responder Agent DID: ${status.responderAgentDid}`
             );
           }
+          if (status.responderProfile) {
+            writeStdoutLine(
+              `Responder Agent Name: ${status.responderProfile.agentName}`
+            );
+            writeStdoutLine(
+              `Responder Human Name: ${status.responderProfile.humanName}`
+            );
+          }
           if (status.peerAlias) {
             writeStdoutLine(`Peer alias saved: ${status.peerAlias}`);
           }
@@ -24067,7 +24257,19 @@ var createPairCommand = (dependencies = {}) => {
         });
         writeStdoutLine("Pairing confirmed");
         writeStdoutLine(`Initiator Agent DID: ${result.initiatorAgentDid}`);
+        writeStdoutLine(
+          `Initiator Agent Name: ${result.initiatorProfile.agentName}`
+        );
+        writeStdoutLine(
+          `Initiator Human Name: ${result.initiatorProfile.humanName}`
+        );
         writeStdoutLine(`Responder Agent DID: ${result.responderAgentDid}`);
+        writeStdoutLine(
+          `Responder Agent Name: ${result.responderProfile.agentName}`
+        );
+        writeStdoutLine(
+          `Responder Human Name: ${result.responderProfile.humanName}`
+        );
         writeStdoutLine(`Paired: ${result.paired ? "true" : "false"}`);
         if (result.peerAlias) {
           writeStdoutLine(`Peer alias saved: ${result.peerAlias}`);
@@ -24099,9 +24301,23 @@ var createPairCommand = (dependencies = {}) => {
         });
         writeStdoutLine(`Status: ${result.status}`);
         writeStdoutLine(`Initiator Agent DID: ${result.initiatorAgentDid}`);
+        writeStdoutLine(
+          `Initiator Agent Name: ${result.initiatorProfile.agentName}`
+        );
+        writeStdoutLine(
+          `Initiator Human Name: ${result.initiatorProfile.humanName}`
+        );
         if (result.responderAgentDid) {
           writeStdoutLine(`Responder Agent DID: ${result.responderAgentDid}`);
         }
+        if (result.responderProfile) {
+          writeStdoutLine(
+            `Responder Agent Name: ${result.responderProfile.agentName}`
+          );
+          writeStdoutLine(
+            `Responder Human Name: ${result.responderProfile.humanName}`
+          );
+        }
         writeStdoutLine(`Expires At: ${result.expiresAt}`);
         if (result.confirmedAt) {
           writeStdoutLine(`Confirmed At: ${result.confirmedAt}`);

package/dist/index.js

@@ -17084,7 +17084,8 @@ var FILE_MODE = 384;
 var ENV_KEY_MAP = {
   registryUrl: "CLAWDENTITY_REGISTRY_URL",
   proxyUrl: "CLAWDENTITY_PROXY_URL",
-  apiKey: "CLAWDENTITY_API_KEY"
+  apiKey: "CLAWDENTITY_API_KEY",
+  humanName: "CLAWDENTITY_HUMAN_NAME"
 };
 var LEGACY_ENV_KEY_MAP = {
   registryUrl: ["CLAWDENTITY_REGISTRY"]
@@ -17111,6 +17112,9 @@ var normalizeConfig = (raw) => {
   if (typeof raw.apiKey === "string" && raw.apiKey.length > 0) {
     config2.apiKey = raw.apiKey;
   }
+  if (typeof raw.humanName === "string" && raw.humanName.length > 0) {
+    config2.humanName = raw.humanName;
+  }
   return config2;
 };
 var getConfigDir = () => join2(homedir(), CONFIG_DIR);
@@ -18536,7 +18540,8 @@ var logger5 = createLogger({ service: "cli", module: "config" });
 var VALID_KEYS = [
   "registryUrl",
   "proxyUrl",
-  "apiKey"
+  "apiKey",
+  "humanName"
 ];
 var isValidConfigKey = (value) => {
   return VALID_KEYS.includes(value);
@@ -20862,11 +20867,20 @@ function parseInviteRedeemResponse(payload) {
   }
   const apiKeyId = parseNonEmptyString7(apiKeySource.id);
   const apiKeyName = parseNonEmptyString7(apiKeySource.name);
+  const humanSource = isRecord7(payload.human) ? payload.human : void 0;
+  const humanName = parseNonEmptyString7(humanSource?.displayName);
   const proxyUrl = parseNonEmptyString7(payload.proxyUrl);
+  if (humanName.length === 0) {
+    throw createCliError5(
+      "CLI_INVITE_REDEEM_INVALID_RESPONSE",
+      "Invite redeem response is invalid"
+    );
+  }
   return {
     apiKeyToken,
     apiKeyId: apiKeyId.length > 0 ? apiKeyId : void 0,
     apiKeyName: apiKeyName.length > 0 ? apiKeyName : void 0,
+    humanName,
     proxyUrl
   };
 }
@@ -20921,6 +20935,14 @@ async function redeemInvite(code, options, dependencies = {}) {
       "Invite code is required"
     );
   }
+  const displayName = parseNonEmptyString7(options.displayName);
+  if (displayName.length === 0) {
+    throw createCliError5(
+      "CLI_INVITE_REDEEM_DISPLAY_NAME_REQUIRED",
+      "Display name is required. Pass --display-name <name>."
+    );
+  }
+  const apiKeyName = parseNonEmptyString7(options.apiKeyName);
   const runtime = await resolveInviteRuntime(options.registryUrl, dependencies);
   const response = await executeInviteRequest({
     fetchImpl: runtime.fetchImpl,
@@ -20930,7 +20952,11 @@ async function redeemInvite(code, options, dependencies = {}) {
       headers: {
         "content-type": "application/json"
       },
-      body: JSON.stringify({ code: inviteCode })
+      body: JSON.stringify({
+        code: inviteCode,
+        displayName,
+        apiKeyName: apiKeyName.length > 0 ? apiKeyName : void 0
+      })
     }
   });
   const responseBody = await parseJsonResponse5(response);
@@ -20950,12 +20976,13 @@ async function redeemInvite(code, options, dependencies = {}) {
     registryUrl: runtime.registryUrl
   };
 }
-async function persistRedeemConfig(registryUrl, apiKeyToken, proxyUrl, dependencies = {}) {
+async function persistRedeemConfig(registryUrl, apiKeyToken, proxyUrl, humanName, dependencies = {}) {
   const setConfigValueImpl = dependencies.setConfigValueImpl ?? setConfigValue;
   try {
     await setConfigValueImpl("registryUrl", registryUrl);
     await setConfigValueImpl("apiKey", apiKeyToken);
     await setConfigValueImpl("proxyUrl", proxyUrl);
+    await setConfigValueImpl("humanName", humanName);
   } catch (error48) {
     logger7.warn("cli.invite_redeem_config_persist_failed", {
       errorName: error48 instanceof Error ? error48.name : "unknown"
@@ -20989,7 +21016,10 @@ var createInviteCommand = (dependencies = {}) => {
       }
     )
   );
-  inviteCommand.command("redeem <code>").description("Redeem a registry invite code and store PAT locally").option("--registry-url <url>", "Override registry URL").action(
+  inviteCommand.command("redeem <code>").description("Redeem a registry invite code and store PAT locally").requiredOption(
+    "--display-name <name>",
+    "Human display name used for onboarding"
+  ).option("--api-key-name <name>", "Optional API key label").option("--registry-url <url>", "Override registry URL").action(
     withErrorHandling(
       "invite redeem",
       async (code, options) => {
@@ -20997,9 +21027,11 @@ var createInviteCommand = (dependencies = {}) => {
         logger7.info("cli.invite_redeemed", {
           apiKeyId: result.apiKeyId,
           apiKeyName: result.apiKeyName,
+          humanName: result.humanName,
           registryUrl: result.registryUrl
         });
         writeStdoutLine("Invite redeemed");
+        writeStdoutLine(`Human name: ${result.humanName}`);
         if (result.apiKeyName) {
           writeStdoutLine(`API key name: ${result.apiKeyName}`);
         }
@@ -21009,6 +21041,7 @@ var createInviteCommand = (dependencies = {}) => {
           result.registryUrl,
           result.apiKeyToken,
           result.proxyUrl,
+          result.humanName,
           dependencies
         );
         writeStdoutLine("API key saved to local config");
@@ -21113,11 +21146,11 @@ function parseNonEmptyString8(value, label) {
   }
   return trimmed;
 }
-function parseOptionalName(value) {
+function parseOptionalProfileName(value, label) {
   if (value === void 0) {
     return void 0;
   }
-  return parseNonEmptyString8(value, "name");
+  return parseNonEmptyString8(value, label);
 }
 function parsePeerAlias(value) {
   const alias = parseNonEmptyString8(value, "peer alias");
@@ -21374,12 +21407,13 @@ async function loadPeersConfig(peersPath) {
     }
     const did = parseAgentDid2(value.did, `Peer ${normalizedAlias} did`);
     const proxyUrl = parseProxyUrl(value.proxyUrl);
-    const name = parseOptionalName(value.name);
-    if (name === void 0) {
+    const agentName = parseOptionalProfileName(value.agentName, "agentName");
+    const humanName = parseOptionalProfileName(value.humanName, "humanName");
+    if (agentName === void 0 && humanName === void 0) {
       peers[normalizedAlias] = { did, proxyUrl };
       continue;
     }
-    peers[normalizedAlias] = { did, proxyUrl, name };
+    peers[normalizedAlias] = { did, proxyUrl, agentName, humanName };
   }
   return { peers };
 }
@@ -22978,6 +23012,7 @@ var FILE_MODE4 = 384;
 var PEER_ALIAS_PATTERN2 = /^[a-zA-Z0-9._-]+$/;
 var DEFAULT_STATUS_WAIT_SECONDS = 300;
 var DEFAULT_STATUS_POLL_INTERVAL_SECONDS = 3;
+var MAX_PROFILE_NAME_LENGTH = 64;
 var isRecord9 = (value) => {
   return typeof value === "object" && value !== null;
 };
@@ -22994,6 +23029,49 @@ function parseNonEmptyString9(value) {
   }
   return value.trim();
 }
+function hasControlChars2(value) {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code <= 31 || code === 127) {
+      return true;
+    }
+  }
+  return false;
+}
+function parseProfileName(value, label) {
+  const candidate = parseNonEmptyString9(value);
+  if (candidate.length === 0) {
+    throw createCliError7(
+      "CLI_PAIR_PROFILE_INVALID",
+      `${label} is required for pairing`
+    );
+  }
+  if (candidate.length > MAX_PROFILE_NAME_LENGTH) {
+    throw createCliError7(
+      "CLI_PAIR_PROFILE_INVALID",
+      `${label} must be at most ${MAX_PROFILE_NAME_LENGTH} characters`
+    );
+  }
+  if (hasControlChars2(candidate)) {
+    throw createCliError7(
+      "CLI_PAIR_PROFILE_INVALID",
+      `${label} contains control characters`
+    );
+  }
+  return candidate;
+}
+function parsePeerProfile(payload) {
+  if (!isRecord9(payload)) {
+    throw createCliError7(
+      "CLI_PAIR_PROFILE_INVALID",
+      "Pair profile must be an object"
+    );
+  }
+  return {
+    agentName: parseProfileName(payload.agentName, "agentName"),
+    humanName: parseProfileName(payload.humanName, "humanName")
+  };
+}
 function parsePairingTicket(value) {
   const ticket = parseNonEmptyString9(value);
   if (!ticket.startsWith(PAIRING_TICKET_PREFIX)) {
@@ -23158,10 +23236,19 @@ function parsePeerEntry(value) {
       "Peer entry is invalid"
     );
   }
-  return {
+  const agentNameRaw = parseNonEmptyString9(value.agentName);
+  const humanNameRaw = parseNonEmptyString9(value.humanName);
+  const entry = {
     did,
     proxyUrl
   };
+  if (agentNameRaw.length > 0) {
+    entry.agentName = parseProfileName(agentNameRaw, "agentName");
+  }
+  if (humanNameRaw.length > 0) {
+    entry.humanName = parseProfileName(humanNameRaw, "humanName");
+  }
+  return entry;
 }
 async function loadPeersConfig2(input) {
   const peersPath = resolvePeersConfigPath(input.getConfigDirImpl);
@@ -23244,6 +23331,19 @@ function parsePositiveIntegerOption(input) {
   }
   return parsed;
 }
+function resolveLocalPairProfile(input) {
+  const humanName = parseNonEmptyString9(input.config.humanName);
+  if (humanName.length === 0) {
+    throw createCliError7(
+      "CLI_PAIR_HUMAN_NAME_MISSING",
+      "Human name is missing. Run `clawdentity invite redeem <clw_inv_...> --display-name <name>` or `clawdentity config set humanName <name>`."
+    );
+  }
+  return {
+    agentName: parseProfileName(input.agentName, "agentName"),
+    humanName: parseProfileName(humanName, "humanName")
+  };
+}
 function parseProxyUrl2(candidate) {
   try {
     const parsed = new URL(candidate);
@@ -23394,15 +23494,25 @@ function parsePairStartResponse(payload) {
   const ticket = parsePairingTicket(payload.ticket);
   const initiatorAgentDid = parseNonEmptyString9(payload.initiatorAgentDid);
   const expiresAt = parseNonEmptyString9(payload.expiresAt);
+  let initiatorProfile;
   if (initiatorAgentDid.length === 0 || expiresAt.length === 0) {
     throw createCliError7(
       "CLI_PAIR_START_INVALID_RESPONSE",
       "Pair start response is invalid"
     );
   }
+  try {
+    initiatorProfile = parsePeerProfile(payload.initiatorProfile);
+  } catch {
+    throw createCliError7(
+      "CLI_PAIR_START_INVALID_RESPONSE",
+      "Pair start response is invalid"
+    );
+  }
   return {
     ticket,
     initiatorAgentDid,
+    initiatorProfile,
     expiresAt
   };
 }
@@ -23416,16 +23526,29 @@ function parsePairConfirmResponse(payload) {
   const paired = payload.paired === true;
   const initiatorAgentDid = parseNonEmptyString9(payload.initiatorAgentDid);
   const responderAgentDid = parseNonEmptyString9(payload.responderAgentDid);
+  let initiatorProfile;
+  let responderProfile;
   if (!paired || initiatorAgentDid.length === 0 || responderAgentDid.length === 0) {
     throw createCliError7(
       "CLI_PAIR_CONFIRM_INVALID_RESPONSE",
       "Pair confirm response is invalid"
     );
   }
+  try {
+    initiatorProfile = parsePeerProfile(payload.initiatorProfile);
+    responderProfile = parsePeerProfile(payload.responderProfile);
+  } catch {
+    throw createCliError7(
+      "CLI_PAIR_CONFIRM_INVALID_RESPONSE",
+      "Pair confirm response is invalid"
+    );
+  }
   return {
     paired,
     initiatorAgentDid,
-    responderAgentDid
+    responderAgentDid,
+    initiatorProfile,
+    responderProfile
   };
 }
 function parsePairStatusResponse(payload) {
@@ -23446,6 +23569,7 @@ function parsePairStatusResponse(payload) {
   const responderAgentDid = parseNonEmptyString9(payload.responderAgentDid);
   const expiresAt = parseNonEmptyString9(payload.expiresAt);
   const confirmedAt = parseNonEmptyString9(payload.confirmedAt);
+  let initiatorProfile;
   if (initiatorAgentDid.length === 0 || expiresAt.length === 0) {
     throw createCliError7(
       "CLI_PAIR_STATUS_INVALID_RESPONSE",
@@ -23458,10 +23582,37 @@ function parsePairStatusResponse(payload) {
       "Pair status response is invalid"
     );
   }
+  try {
+    initiatorProfile = parsePeerProfile(payload.initiatorProfile);
+  } catch {
+    throw createCliError7(
+      "CLI_PAIR_STATUS_INVALID_RESPONSE",
+      "Pair status response is invalid"
+    );
+  }
+  let responderProfile;
+  if (payload.responderProfile !== void 0) {
+    try {
+      responderProfile = parsePeerProfile(payload.responderProfile);
+    } catch {
+      throw createCliError7(
+        "CLI_PAIR_STATUS_INVALID_RESPONSE",
+        "Pair status response is invalid"
+      );
+    }
+  }
+  if (statusRaw === "confirmed" && responderProfile === void 0) {
+    throw createCliError7(
+      "CLI_PAIR_STATUS_INVALID_RESPONSE",
+      "Pair status response is invalid"
+    );
+  }
   return {
     status: statusRaw,
     initiatorAgentDid,
+    initiatorProfile,
     responderAgentDid: responderAgentDid.length > 0 ? responderAgentDid : void 0,
+    responderProfile,
     expiresAt,
     confirmedAt: confirmedAt.length > 0 ? confirmedAt : void 0
   };
@@ -23666,7 +23817,9 @@ async function persistPairedPeer(input) {
   });
   peersConfig.peers[alias] = {
     did: input.peerDid,
-    proxyUrl: peerProxyUrl
+    proxyUrl: peerProxyUrl,
+    agentName: input.peerProfile.agentName,
+    humanName: input.peerProfile.humanName
   };
   await savePeersConfig2({
     config: peersConfig,
@@ -23688,13 +23841,19 @@ async function startPairing(agentName, options, dependencies = {}) {
     config: config2,
     fetchImpl
   });
+  const normalizedAgentName = assertValidAgentName(agentName);
+  const initiatorProfile = resolveLocalPairProfile({
+    config: config2,
+    agentName: normalizedAgentName
+  });
   const { ait, secretKey } = await readAgentProofMaterial(
-    agentName,
+    normalizedAgentName,
     dependencies
   );
   const requestUrl = toProxyRequestUrl(proxyUrl, PAIR_START_PATH);
   const requestBody = JSON.stringify({
-    ttlSeconds
+    ttlSeconds,
+    initiatorProfile
   });
   const bodyBytes = new TextEncoder().encode(requestBody);
   const timestampSeconds = nowSecondsImpl();
@@ -23751,6 +23910,11 @@ async function confirmPairing(agentName, options, dependencies = {}) {
   const readFileImpl = dependencies.readFileImpl ?? readFile6;
   const qrDecodeImpl = dependencies.qrDecodeImpl ?? decodeTicketFromPng;
   const config2 = await resolveConfigImpl();
+  const normalizedAgentName = assertValidAgentName(agentName);
+  const responderProfile = resolveLocalPairProfile({
+    config: config2,
+    agentName: normalizedAgentName
+  });
   const ticketSource = resolveConfirmTicketSource(options);
   const proxyUrl = await resolveProxyUrl({
     config: config2,
@@ -23780,11 +23944,14 @@ async function confirmPairing(agentName, options, dependencies = {}) {
     ticket = parsePairingTicket(qrDecodeImpl(new Uint8Array(imageBytes)));
   }
   const { ait, secretKey } = await readAgentProofMaterial(
-    agentName,
+    normalizedAgentName,
     dependencies
   );
   const requestUrl = toProxyRequestUrl(proxyUrl, PAIR_CONFIRM_PATH);
-  const requestBody = JSON.stringify({ ticket });
+  const requestBody = JSON.stringify({
+    ticket,
+    responderProfile
+  });
   const bodyBytes = new TextEncoder().encode(requestBody);
   const timestampSeconds = nowSecondsImpl();
   const nonce = nonceFactoryImpl();
@@ -23820,6 +23987,7 @@ async function confirmPairing(agentName, options, dependencies = {}) {
   const peerAlias = await persistPairedPeer({
     ticket,
     peerDid: parsed.initiatorAgentDid,
+    peerProfile: parsed.initiatorProfile,
     dependencies
   });
   if (ticketSource.source === "qr-file" && ticketSource.qrFilePath) {
@@ -23901,15 +24069,23 @@ async function getPairingStatusOnce(agentName, options, dependencies = {}) {
       );
     }
     const peerDid = callerAgentDid === parsed.initiatorAgentDid ? responderAgentDid : callerAgentDid === responderAgentDid ? parsed.initiatorAgentDid : void 0;
+    const peerProfile = callerAgentDid === parsed.initiatorAgentDid ? parsed.responderProfile : callerAgentDid === responderAgentDid ? parsed.initiatorProfile : void 0;
     if (!peerDid) {
       throw createCliError7(
         "CLI_PAIR_STATUS_FORBIDDEN",
         "Local agent is not a participant in the pairing ticket"
       );
     }
+    if (!peerProfile) {
+      throw createCliError7(
+        "CLI_PAIR_STATUS_INVALID_RESPONSE",
+        "Pair status response is invalid"
+      );
+    }
     peerAlias = await persistPairedPeer({
       ticket,
       peerDid,
+      peerProfile,
       dependencies
     });
   }
@@ -24005,6 +24181,12 @@ var createPairCommand = (dependencies = {}) => {
         writeStdoutLine("Pairing ticket created");
         writeStdoutLine(`Ticket: ${result.ticket}`);
         writeStdoutLine(`Initiator Agent DID: ${result.initiatorAgentDid}`);
+        writeStdoutLine(
+          `Initiator Agent Name: ${result.initiatorProfile.agentName}`
+        );
+        writeStdoutLine(
+          `Initiator Human Name: ${result.initiatorProfile.humanName}`
+        );
         writeStdoutLine(`Expires At: ${result.expiresAt}`);
         if (result.qrPath) {
           writeStdoutLine(`QR File: ${result.qrPath}`);
@@ -24047,6 +24229,14 @@ var createPairCommand = (dependencies = {}) => {
               `Responder Agent DID: ${status.responderAgentDid}`
             );
           }
+          if (status.responderProfile) {
+            writeStdoutLine(
+              `Responder Agent Name: ${status.responderProfile.agentName}`
+            );
+            writeStdoutLine(
+              `Responder Human Name: ${status.responderProfile.humanName}`
+            );
+          }
           if (status.peerAlias) {
             writeStdoutLine(`Peer alias saved: ${status.peerAlias}`);
           }
@@ -24067,7 +24257,19 @@ var createPairCommand = (dependencies = {}) => {
         });
         writeStdoutLine("Pairing confirmed");
         writeStdoutLine(`Initiator Agent DID: ${result.initiatorAgentDid}`);
+        writeStdoutLine(
+          `Initiator Agent Name: ${result.initiatorProfile.agentName}`
+        );
+        writeStdoutLine(
+          `Initiator Human Name: ${result.initiatorProfile.humanName}`
+        );
         writeStdoutLine(`Responder Agent DID: ${result.responderAgentDid}`);
+        writeStdoutLine(
+          `Responder Agent Name: ${result.responderProfile.agentName}`
+        );
+        writeStdoutLine(
+          `Responder Human Name: ${result.responderProfile.humanName}`
+        );
         writeStdoutLine(`Paired: ${result.paired ? "true" : "false"}`);
         if (result.peerAlias) {
           writeStdoutLine(`Peer alias saved: ${result.peerAlias}`);
@@ -24099,9 +24301,23 @@ var createPairCommand = (dependencies = {}) => {
         });
         writeStdoutLine(`Status: ${result.status}`);
         writeStdoutLine(`Initiator Agent DID: ${result.initiatorAgentDid}`);
+        writeStdoutLine(
+          `Initiator Agent Name: ${result.initiatorProfile.agentName}`
+        );
+        writeStdoutLine(
+          `Initiator Human Name: ${result.initiatorProfile.humanName}`
+        );
         if (result.responderAgentDid) {
           writeStdoutLine(`Responder Agent DID: ${result.responderAgentDid}`);
         }
+        if (result.responderProfile) {
+          writeStdoutLine(
+            `Responder Agent Name: ${result.responderProfile.agentName}`
+          );
+          writeStdoutLine(
+            `Responder Human Name: ${result.responderProfile.humanName}`
+          );
+        }
         writeStdoutLine(`Expires At: ${result.expiresAt}`);
         if (result.confirmedAt) {
           writeStdoutLine(`Confirmed At: ${result.confirmedAt}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawdentity",
-  "version": "0.0.17",
+  "version": "0.0.18",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -21,17 +21,6 @@
     "postinstall.mjs",
     "skill-bundle"
   ],
-  "scripts": {
-    "build": "pnpm -F @clawdentity/openclaw-skill build && pnpm run sync:skill-bundle && pnpm run verify:skill-bundle && tsup",
-    "format": "biome format .",
-    "lint": "biome lint .",
-    "prepack": "pnpm run build",
-    "postinstall": "node ./postinstall.mjs",
-    "sync:skill-bundle": "node ./scripts/sync-skill-bundle.mjs",
-    "verify:skill-bundle": "node ./scripts/verify-skill-bundle.mjs",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
-  },
   "dependencies": {
     "commander": "^13.1.0",
     "jsqr": "^1.4.0",
@@ -40,11 +29,21 @@
     "ws": "^8.19.0"
   },
   "devDependencies": {
-    "@clawdentity/connector": "workspace:*",
-    "@clawdentity/protocol": "workspace:*",
-    "@clawdentity/sdk": "workspace:*",
     "@types/node": "^22.18.11",
     "@types/pngjs": "^6.0.5",
-    "@types/qrcode": "^1.5.6"
+    "@types/qrcode": "^1.5.6",
+    "@clawdentity/connector": "0.0.0",
+    "@clawdentity/protocol": "0.0.0",
+    "@clawdentity/sdk": "0.0.0"
+  },
+  "scripts": {
+    "build": "pnpm -F @clawdentity/openclaw-skill build && pnpm run sync:skill-bundle && pnpm run verify:skill-bundle && tsup",
+    "format": "biome format .",
+    "lint": "biome lint .",
+    "postinstall": "node ./postinstall.mjs",
+    "sync:skill-bundle": "node ./scripts/sync-skill-bundle.mjs",
+    "verify:skill-bundle": "node ./scripts/verify-skill-bundle.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
-}
+}

package/skill-bundle/openclaw-skill/dist/relay-to-peer.mjs

@@ -56,11 +56,11 @@ function parseProxyUrl(value) {
     throw new Error("proxyUrl must be a valid URL");
   }
 }
-function parsePeerName(value) {
+function parseProfileName(value, label) {
   if (value === void 0) {
     return void 0;
   }
-  return parseNonEmptyString(value, "name");
+  return parseNonEmptyString(value, label);
 }
 function parsePeerEntry(value) {
   if (!isRecord(value)) {
@@ -68,11 +68,12 @@ function parsePeerEntry(value) {
   }
   const did = parseDid(value.did);
   const proxyUrl = parseProxyUrl(value.proxyUrl);
-  const name = parsePeerName(value.name);
-  if (name === void 0) {
+  const agentName = parseProfileName(value.agentName, "agentName");
+  const humanName = parseProfileName(value.humanName, "humanName");
+  if (agentName === void 0 && humanName === void 0) {
     return { did, proxyUrl };
   }
-  return { did, proxyUrl, name };
+  return { did, proxyUrl, agentName, humanName };
 }
 function parsePeersConfig(value, source) {
   if (!isRecord(value)) {

package/skill-bundle/openclaw-skill/skill/SKILL.md

@@ -57,6 +57,7 @@ Relay invite codes are not part of this flow.
 Required for onboarding:
 - Registry onboarding invite code: `clw_inv_...` (default onboarding path)
 - Local agent name
+- Human display name (used by invite redeem and pairing profile metadata)
 
 Optional only for recovery/advanced operator flows:
 - Existing API key (only when user explicitly says no invite is available)
@@ -84,8 +85,8 @@ Note: Registry operators must run `admin bootstrap` before creating invites. See
 - `clawdentity config show`
 
 ### Invite management
-- `clawdentity invite redeem <registry-invite-code>`
-- `clawdentity invite redeem <registry-invite-code> --registry-url <registry-url>`
+- `clawdentity invite redeem <registry-invite-code> --display-name <human-name>`
+- `clawdentity invite redeem <registry-invite-code> --display-name <human-name> --registry-url <registry-url>`
 - `clawdentity invite create` (admin only, see registry reference)
 - `clawdentity invite create --expires-at <iso-8601>` (admin only)
 
@@ -152,6 +153,7 @@ Note: Registry operators must run `admin bootstrap` before creating invites. See
 - If `--invite-code` appears, treat CLI as outdated and upgrade before continuing:
   - `npm install -g clawdentity@latest`
 - Confirm local agent name.
+- Confirm local human display name for onboarding.
 - Check local API key status with `clawdentity config get apiKey`.
 - If API key is missing, ask for onboarding invite `clw_inv_...` and continue with invite redeem.
 - Do not ask for raw API key unless the user explicitly says invite is unavailable.
@@ -167,13 +169,14 @@ Note: Registry operators must run `admin bootstrap` before creating invites. See
 - If needed, run with `--registry-url`.
 
 4. Finish onboarding and generate API key.
-- Preferred path: run `clawdentity invite redeem <clw_inv_...>`.
+- Preferred path: run `clawdentity invite redeem <clw_inv_...> --display-name <human-name>`.
 - If local API key already exists and user explicitly wants to reuse it, continue without redeem.
 - Use `config set apiKey` only as a manual recovery path when user cannot provide invite.
 - Confirm output shows:
   - `Invite redeemed`
   - API key token printed once
   - `API key saved to local config`
+  - `Human name: <human-name>`
 - Stop and fix if this step fails. Do not proceed to pairing.
 
 5. Create local OpenClaw agent identity.
@@ -226,6 +229,14 @@ Note: Registry operators must run `admin bootstrap` before creating invites. See
   - Inline ticket path: `clawdentity pair confirm <agent-name> --ticket <clwpair1_...>`
   - Cannot provide both `--qr-file` and `--ticket` simultaneously.
 - Pair confirm auto-saves peer DID/proxy mapping locally from QR ticket metadata.
+- Pair start/confirm/status exchange profile metadata:
+  - `initiatorProfile = { agentName, humanName }`
+  - `responderProfile = { agentName, humanName }`
+- Local peer entries in `~/.clawdentity/peers.json` should include:
+  - `did`
+  - `proxyUrl`
+  - `agentName`
+  - `humanName`
 - If initiator started without `--wait`, initiator must run:
   - `clawdentity pair status <agent-name> --ticket <clwpair1_...> --wait`
   - This persists the peer on initiator after responder confirmation.
@@ -236,6 +247,8 @@ Note: Registry operators must run `admin bootstrap` before creating invites. See
 - Verify output shows token status, expiry, and no revocation.
 - Run `clawdentity openclaw doctor --peer <alias>` to confirm the new peer is visible.
 - Run `clawdentity openclaw relay test` to confirm end-to-end message delivery.
+- Relay delivery is asynchronous: proxy accepts deliveries with `202`, and `state=queued` is expected when the recipient connector is temporarily offline.
+- `state=queued` is not a pairing failure. The proxy retries delivery automatically while the message is within queue TTL/retry limits.
 - Note: `relay test` runs preflight doctor checks before sending the probe.
 
 ## Lifecycle Management

package/skill-bundle/openclaw-skill/skill/references/clawdentity-protocol.md

@@ -51,7 +51,8 @@ Rules:
     "beta": {
       "did": "did:claw:agent:01H...",
       "proxyUrl": "https://beta-proxy.example.com/hooks/agent",
-      "name": "Beta Agent"
+      "agentName": "beta",
+      "humanName": "Ira"
     }
   }
 }
@@ -61,7 +62,8 @@ Rules:
 - peer alias key uses `[a-zA-Z0-9._-]`
 - `did` required and must begin with `did:`
 - `proxyUrl` required and must be a valid absolute URL
-- `name` optional
+- `agentName` optional
+- `humanName` optional
 
 ## Proxy Pairing Prerequisite
 
@@ -75,11 +77,15 @@ Current pairing contract is ticket-based with CLI support:
    - headers:
      - `Authorization: Claw <AIT>`
      - ownership validation is handled internally by proxy-to-registry service auth
-   - body (optional):
+   - body:
 
 ```json
 {
-  "ttlSeconds": 300
+  "ttlSeconds": 300,
+  "initiatorProfile": {
+    "agentName": "alpha",
+    "humanName": "Ravi"
+  }
 }
 ```
 
@@ -92,7 +98,11 @@ Current pairing contract is ticket-based with CLI support:
 
 ```json
 {
-  "ticket": "clwpair1_..."
+  "ticket": "clwpair1_...",
+  "responderProfile": {
+    "agentName": "beta",
+    "humanName": "Ira"
+  }
 }
 ```
 
@@ -202,7 +212,7 @@ Known defaults:
 | `https://registry.clawdentity.com` | `https://proxy.clawdentity.com` |
 | `https://dev.registry.clawdentity.com` | `https://dev.proxy.clawdentity.com` |
 
-Recovery: rerun onboarding (`clawdentity invite redeem <clw_inv_...>`) so local config aligns to registry metadata.
+Recovery: rerun onboarding (`clawdentity invite redeem <clw_inv_...> --display-name <human-name>`) so local config aligns to registry metadata.
 
 ## Pairing Error Codes
 
@@ -213,6 +223,7 @@ Recovery: rerun onboarding (`clawdentity invite redeem <clw_inv_...>`) so local
 | 403 | `PROXY_PAIR_OWNERSHIP_FORBIDDEN` | Initiator ownership check failed |
 | 503 | `PROXY_PAIR_OWNERSHIP_UNAVAILABLE` | Registry ownership lookup unavailable |
 | — | `CLI_PAIR_AGENT_NOT_FOUND` | Agent ait.jwt or secret.key missing/empty |
+| — | `CLI_PAIR_HUMAN_NAME_MISSING` | Local config is missing `humanName`; set via invite redeem or config |
 | — | `CLI_PAIR_PROXY_URL_REQUIRED` | Proxy URL could not be resolved |
 | — | `CLI_PAIR_START_INVALID_TTL` | ttlSeconds must be a positive integer |
 | — | `CLI_PAIR_INVALID_PROXY_URL` | Proxy URL is invalid |