@xfxstudio/claworld 0.2.9 → 0.2.10-beta.0

package/src/openclaw/plugin/claworld-channel-plugin.js

@@ -45,12 +45,14 @@ import {
   resolveWorldSelection,
   resolveWorldSelectionFlow,
 } from '../runtime/product-shell-helper.js';
+import { extractBackendErrorContext } from '../runtime/backend-error-context.js';
 import { getClaworldRuntime } from './runtime.js';
 import {
   createRuntimeBoundaryError,
   normalizeRuntimeBoundaryError,
   serializeRuntimeBoundaryError,
 } from '../../lib/runtime-errors.js';
+import { v4 as uuidv4 } from 'uuid';
 
 function normalizeRelayHttpBaseUrl(serverUrl) {
   const parsed = new URL(serverUrl);
@@ -67,108 +69,16 @@ function normalizePluginOptionalText(value) {
   return normalized || null;
 }
 
-function inferRelayDomain(runtimeConfig = {}) {
-  const defaultToAddress = String(runtimeConfig.relay?.defaultToAddress || '').trim();
-  const atIndex = defaultToAddress.indexOf('@');
-  if (atIndex > 0 && atIndex < defaultToAddress.length - 1) {
-    return defaultToAddress.slice(atIndex + 1).trim().toLowerCase();
-  }
-  return 'relay.local';
-}
-
-const RELAY_LOCAL_AGENT_CODE_PATTERN = /^[A-Za-z0-9._:+~-]+$/;
-const RELAY_CANONICAL_AGENT_CODE_PATTERN = /^[A-Za-z0-9._:+~-]+@[A-Za-z0-9._:+~-]+$/;
-
-function normalizeRelayDomainName(value, fallback = null) {
-  const normalized = normalizeClaworldText(value, fallback)?.toLowerCase() || null;
-  if (!normalized) return fallback;
-  if (!/^[a-z0-9._:+~-]+$/.test(normalized)) return fallback;
-  return normalized;
-}
-
-function normalizeRelayLocalAgentCode(value, fallback = null) {
-  const normalized = normalizeClaworldText(value, fallback)?.toLowerCase() || null;
-  if (!normalized) return fallback;
-  if (!RELAY_LOCAL_AGENT_CODE_PATTERN.test(normalized)) return fallback;
-  return normalized;
-}
-
-function parseCanonicalRelayAgentCode(value) {
-  const normalized = normalizeClaworldText(value, null)?.toLowerCase() || null;
-  if (!normalized || !RELAY_CANONICAL_AGENT_CODE_PATTERN.test(normalized)) return null;
-  const atIndex = normalized.indexOf('@');
-  if (atIndex <= 0 || atIndex >= normalized.length - 1) return null;
-  const relayLocalCode = normalizeRelayLocalAgentCode(normalized.slice(0, atIndex), null);
-  const domain = normalizeRelayDomainName(normalized.slice(atIndex + 1), null);
-  if (!relayLocalCode || !domain) return null;
-  return {
-    agentCode: `${relayLocalCode}@${domain}`,
-    relayLocalCode,
-    domain,
-  };
-}
-
-function buildCanonicalRelayAgentCode(relayLocalCode, runtimeConfig = {}, domainOverride = null) {
-  const normalizedRelayLocalCode = normalizeRelayLocalAgentCode(relayLocalCode, null);
-  const domain = normalizeRelayDomainName(domainOverride, null)
-    || normalizeRelayDomainName(inferRelayDomain(runtimeConfig), null);
-  if (!normalizedRelayLocalCode || !domain) return null;
-  return `${normalizedRelayLocalCode}@${domain}`;
-}
-
-function normalizeCanonicalRelayAgentCode(value, runtimeConfig = {}) {
-  const parsed = parseCanonicalRelayAgentCode(value);
-  if (parsed) return parsed.agentCode;
-  const relayLocalCode = normalizeRelayLocalAgentCode(value, null);
-  if (!relayLocalCode) return null;
-  return buildCanonicalRelayAgentCode(relayLocalCode, runtimeConfig);
-}
-
-function normalizeRelayIdentityInput({ runtimeConfig = {}, agentId = null, agentCode = null, address = null } = {}) {
-  const normalizedAgentId = normalizeClaworldText(agentId, null);
-  const normalizedAddress = normalizeClaworldText(resolveRelayAddress(address || agentCode || '', runtimeConfig), null)?.toLowerCase() || null;
-  const parsedCanonicalAgentCode = parseCanonicalRelayAgentCode(agentCode)
-    || parseCanonicalRelayAgentCode(normalizedAddress);
-  const relayLocalCode = normalizeRelayLocalAgentCode(agentCode, null)
-    || parsedCanonicalAgentCode?.relayLocalCode
-    || null;
-  const domain = parsedCanonicalAgentCode?.domain
-    || normalizeRelayDomainName(normalizedAddress?.split('@')[1], null)
-    || normalizeRelayDomainName(inferRelayDomain(runtimeConfig), null);
-  const normalizedAgentCode = parsedCanonicalAgentCode?.agentCode
-    || (relayLocalCode ? buildCanonicalRelayAgentCode(relayLocalCode, runtimeConfig, domain) : null)
-    || null;
-
-  return {
-    agentId: normalizedAgentId,
-    agentCode: normalizedAgentCode,
-    relayLocalCode,
-    address: normalizedAddress || normalizedAgentCode || null,
-    domain,
-  };
+function resolveClientMessageId(value = null) {
+  return normalizePluginOptionalText(value) || `cmsg_${uuidv4()}`;
 }
 
-function buildRelayAgentSummary(item = {}, runtimeConfig = {}) {
+function buildRelayAgentSummary(item = {}) {
   const normalizedAgentId = normalizeClaworldText(item?.agentId, null);
-  const relayLocalCode = normalizeRelayLocalAgentCode(item?.agentCode, null);
-  const address = normalizeClaworldText(item?.address, null)?.toLowerCase()
-    || buildCanonicalRelayAgentCode(relayLocalCode, runtimeConfig, item?.domain)
-    || null;
-  const parsedCanonicalAgentCode = parseCanonicalRelayAgentCode(address);
-  const domain = normalizeRelayDomainName(item?.domain, null)
-    || parsedCanonicalAgentCode?.domain
-    || normalizeRelayDomainName(inferRelayDomain(runtimeConfig), null);
-  const canonicalAgentCode = parsedCanonicalAgentCode?.agentCode
-    || buildCanonicalRelayAgentCode(relayLocalCode, runtimeConfig, domain)
-    || null;
-
   return {
     agentId: normalizedAgentId,
-    agentCode: canonicalAgentCode,
-    relayLocalCode: relayLocalCode || parsedCanonicalAgentCode?.relayLocalCode || null,
-    domain,
-    address: address || canonicalAgentCode || null,
     displayName: normalizeClaworldText(item?.displayName, null),
+    publicIdentity: item?.publicIdentity && typeof item.publicIdentity === 'object' ? item.publicIdentity : null,
     discoverable: typeof item?.discoverable === 'boolean' ? item.discoverable : null,
     contactable: typeof item?.contactable === 'boolean' ? item.contactable : null,
     online: typeof item?.online === 'boolean' ? item.online : null,
@@ -179,19 +89,10 @@ function normalizeClaworldTarget(raw) {
   if (typeof raw !== 'string') return undefined;
   let value = raw.trim();
   if (!value) return undefined;
-  value = value.replace(/^claworld:/i, '').replace(/^user:/i, '').replace(/^@/, '').trim();
+  value = value.replace(/^claworld:/i, '').replace(/^user:/i, '').trim();
   return value || undefined;
 }
 
-function resolveRelayAddress(to, runtimeConfig = {}) {
-  const normalized = normalizeClaworldTarget(typeof to === 'string' ? to : '');
-  const fallback = normalizeClaworldTarget(runtimeConfig.relay?.defaultToAddress || '');
-  const candidate = normalized || fallback;
-  if (!candidate) return '';
-  if (candidate.includes('@')) return candidate.toLowerCase();
-  return `${candidate.toLowerCase()}@${inferRelayDomain(runtimeConfig)}`;
-}
-
 function normalizeClaworldText(value, fallback = null) {
   if (value == null) return fallback;
   const normalized = String(value).trim();
@@ -215,6 +116,45 @@ function shouldAuthorizeBridgedCommand({ runtimeConfig = {}, incomingText }) {
   return typeof incomingText === 'string' && incomingText.trim().startsWith('/');
 }
 
+function normalizeUntrustedContextLines(value) {
+  if (Array.isArray(value)) {
+    return value
+      .map((entry) => resolveNormalizedText(entry, null))
+      .filter(Boolean);
+  }
+  const singleLine = resolveNormalizedText(value, null);
+  return singleLine ? [singleLine] : [];
+}
+
+function mergeUntrustedContextLines(...groups) {
+  const merged = [];
+  const seen = new Set();
+  for (const group of groups) {
+    for (const line of normalizeUntrustedContextLines(group)) {
+      if (seen.has(line)) continue;
+      seen.add(line);
+      merged.push(line);
+    }
+  }
+  return merged;
+}
+
+function parseBridgeTimestampMs(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value !== 'string') return null;
+  const normalized = value.trim();
+  if (!normalized) return null;
+  const parsed = Date.parse(normalized);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function resolveBridgeDeliveryTimestampMs({ delivery = {}, metadata = {} } = {}) {
+  return parseBridgeTimestampMs(delivery?.createdAt)
+    || parseBridgeTimestampMs(delivery?.turnCreatedAt)
+    || parseBridgeTimestampMs(metadata?.createdAt)
+    || Date.now();
+}
+
 const CLAWORLD_RELAY_OPERATIONAL_NOTICE_PATTERNS = [
   /^🧭\s*New session:\s+\S+/i,
   /^🧹\s*Auto-compaction complete(?:\s*\(count \d+\))?\.$/i,
@@ -355,10 +295,11 @@ function buildClaworldDirectoryEntries(config = {}, accountId = null) {
     const account = inspectClaworldChannelAccount(config, id);
     if (!account?.enabled || !account?.configured) continue;
     const normalizedId = String(account.accountId || id || '').trim();
-    if (!normalizedId) continue;
+    const boundAgentId = normalizeClaworldText(account.relay?.agentId, null);
+    if (!normalizedId || !boundAgentId) continue;
     if (currentAccountId && normalizedId === currentAccountId) continue;
     entries.push({
-      id: resolveRelayAddress(normalizedId, account),
+      id: boundAgentId,
       name: normalizedId,
       handle: normalizedId,
       rank: 100,
@@ -366,11 +307,10 @@ function buildClaworldDirectoryEntries(config = {}, accountId = null) {
   }
 
   const current = inspectClaworldChannelAccount(config, currentAccountId || null);
-  const defaultTarget = resolveRelayAddress(current?.relay?.defaultToAddress || '', current || {});
-  if (defaultTarget) {
-    const localPart = defaultTarget.split('@')[0] || defaultTarget;
-    if (!entries.some((entry) => entry.id === defaultTarget)) {
-      entries.push({ id: defaultTarget, name: localPart, handle: localPart, rank: 50 });
+  const defaultTargetAgentId = normalizeClaworldText(current?.relay?.defaultTargetAgentId, null);
+  if (defaultTargetAgentId) {
+    if (!entries.some((entry) => entry.id === defaultTargetAgentId)) {
+      entries.push({ id: defaultTargetAgentId, name: defaultTargetAgentId, handle: defaultTargetAgentId, rank: 50 });
     }
   }
 
@@ -381,8 +321,8 @@ async function deliverRelayMessage({ runtimeConfig, to, text, fetchImpl, logger,
   const fromAgentId = runtimeConfig.relay?.agentId;
   if (!fromAgentId) throw new Error('claworld relay.agentId is required for outbound send');
 
-  const toAddress = resolveRelayAddress(to, runtimeConfig);
-  if (!toAddress) throw new Error('claworld outbound target is required');
+  const targetAgentId = normalizeClaworldText(to, null);
+  if (!targetAgentId) throw new Error('claworld outbound targetAgentId is required');
 
   const normalizedText = normalizeClaworldText(text, null);
   const payload = messagePayload && typeof messagePayload === 'object'
@@ -397,6 +337,9 @@ async function deliverRelayMessage({ runtimeConfig, to, text, fetchImpl, logger,
   }
   payload.source = normalizeClaworldText(payload.source, 'openclaw-claworld');
   payload.accountId = normalizeClaworldText(payload.accountId, runtimeConfig.accountId);
+  const clientMessageId = resolveClientMessageId(
+    outboundContext.clientMessageId || outboundContext.metadata?.clientMessageId || null
+  );
 
   const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
   const result = await fetchJson(fetchImpl, `${baseUrl}/v1/messages`, {
@@ -408,7 +351,8 @@ async function deliverRelayMessage({ runtimeConfig, to, text, fetchImpl, logger,
     },
     body: JSON.stringify({
       fromAgentId,
-      toAddress,
+      targetAgentId,
+      clientMessageId,
       payload,
       conversation: {
         conversationKey: outboundContext.conversationKey || outboundContext.metadata?.conversationKey || null,
@@ -433,7 +377,7 @@ async function deliverRelayMessage({ runtimeConfig, to, text, fetchImpl, logger,
       context: {
         accountId: runtimeConfig.accountId || null,
         fromAgentId,
-        toAddress,
+        targetAgentId,
         status: result.status,
       },
     });
@@ -442,13 +386,14 @@ async function deliverRelayMessage({ runtimeConfig, to, text, fetchImpl, logger,
   return {
     channel: 'claworld',
     messageId: result.body?.turn?.turnId || `turn_${Date.now()}`,
-    chatId: toAddress,
+    chatId: targetAgentId,
     timestamp: Date.now(),
     meta: {
+      clientMessageId,
       sessionKey: result.body?.delivery?.sessionKey || outboundContext.sessionKey || outboundContext.SessionKey || null,
       turnId: result.body?.turn?.turnId || null,
       conversationKey: result.body?.conversationKey || null,
-      toAddress,
+      targetAgentId,
     },
   };
 }
@@ -481,8 +426,7 @@ function createRelayRouteError({
     context: {
       accountId: runtimeConfig.accountId || null,
       httpStatus: result?.status || null,
-      backendCode: result?.body?.error || null,
-      backendMessage: result?.body?.message || null,
+      ...extractBackendErrorContext(result?.body),
       ...context,
     },
   });
@@ -491,7 +435,7 @@ function createRelayRouteError({
 async function createFriendRequest({
   runtimeConfig,
   fromAgentId,
-  toAddress,
+  targetAgentId,
   message = null,
   metadata = {},
   fetchImpl,
@@ -506,7 +450,7 @@ async function createFriendRequest({
     },
     body: JSON.stringify({
       fromAgentId,
-      toAddress,
+      targetAgentId,
       message: normalizeClaworldText(message, null),
       metadata: metadata && typeof metadata === 'object' && !Array.isArray(metadata) ? metadata : {},
     }),
@@ -517,7 +461,7 @@ async function createFriendRequest({
       runtimeConfig,
       code: 'friend_request_failed',
       publicMessage: 'failed to create friend request',
-      context: { fromAgentId, toAddress },
+      context: { fromAgentId, targetAgentId },
     });
   }
   return result.body || {};
@@ -833,16 +777,6 @@ function isNonRecoverableBootstrapHoldError(error) {
 }
 
 function buildBootstrapHoldMessage(error, runtimeConfig = {}) {
-  if (error?.code === 'agent_code_conflict') {
-    const requestedAgentCode = normalizeClaworldText(
-      error?.context?.requestedAgentCode,
-      normalizeRuntimeRegistration(runtimeConfig).agentCode || null,
-    );
-    return requestedAgentCode
-      ? `Claworld setup blocked: relay agent code ${requestedAgentCode} already exists. Add the bound appToken for this account or choose a different registration.agentCode.`
-      : 'Claworld setup blocked: relay agent code already exists. Add the bound appToken for this account or choose a different registration.agentCode.';
-  }
-
   const publicMessage = normalizeClaworldText(error?.publicMessage, null);
   const fallbackMessage = normalizeClaworldText(error?.message, 'relay binding bootstrap failed');
   return `Claworld setup blocked: ${publicMessage || fallbackMessage}`;
@@ -970,6 +904,79 @@ async function fetchJson(fetchImpl, url, init = {}) {
   }
 }
 
+async function fetchPublicIdentity({
+  runtimeConfig,
+  agentId = null,
+  fetchImpl,
+}) {
+  const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
+  const path = buildRelayJsonPath('/v1/profile/public-identity', {
+    agentId,
+  });
+  const result = await fetchJson(fetchImpl, `${baseUrl}${path}`, {
+    method: 'GET',
+    headers: {
+      ...(runtimeConfig.apiKey ? { 'x-api-key': runtimeConfig.apiKey } : {}),
+      ...buildRuntimeAuthHeaders(runtimeConfig),
+    },
+  });
+  if (!result.ok) {
+    createRelayRouteError({
+      result,
+      runtimeConfig,
+      code: 'public_identity_fetch_failed',
+      publicMessage: 'failed to read public identity status',
+      context: { agentId: normalizeClaworldText(agentId, null) },
+    });
+  }
+  return result.body || {};
+}
+
+async function updatePublicIdentity({
+  runtimeConfig,
+  agentId = null,
+  displayName = null,
+  fetchImpl,
+}) {
+  const normalizedDisplayName = normalizeClaworldText(displayName, null);
+  if (!normalizedDisplayName) {
+    throw createRuntimeBoundaryError({
+      code: 'tool_input_invalid',
+      category: 'input',
+      status: 400,
+      message: 'claworld public identity update requires displayName',
+      publicMessage: 'claworld public identity update requires displayName',
+      recoverable: true,
+      context: { field: 'displayName' },
+    });
+  }
+  const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
+  const result = await fetchJson(fetchImpl, `${baseUrl}/v1/profile/public-identity`, {
+    method: 'PUT',
+    headers: {
+      'content-type': 'application/json',
+      ...(runtimeConfig.apiKey ? { 'x-api-key': runtimeConfig.apiKey } : {}),
+      ...buildRuntimeAuthHeaders(runtimeConfig),
+    },
+    body: JSON.stringify({
+      ...(normalizeClaworldText(agentId, null) ? { agentId: normalizeClaworldText(agentId, null) } : {}),
+      displayName: normalizedDisplayName,
+    }),
+  });
+  if (!result.ok) {
+    createRelayRouteError({
+      result,
+      runtimeConfig,
+      code: 'public_identity_update_failed',
+      publicMessage: 'failed to update public identity',
+      context: {
+        agentId: normalizeClaworldText(agentId, null),
+      },
+    });
+  }
+  return result.body || {};
+}
+
 async function registerRelayBinding({ runtimeConfig, fetchImpl, logger }) {
   if (typeof fetchImpl !== 'function') {
     throw new Error('fetch is unavailable for relay registration');
@@ -985,7 +992,6 @@ async function registerRelayBinding({ runtimeConfig, fetchImpl, logger }) {
       ...(runtimeConfig.apiKey ? { 'x-api-key': runtimeConfig.apiKey } : {}),
     }),
     body: JSON.stringify({
-      ...(registration.enabled ? { agentCode: registration.agentCode } : {}),
       ...(registration.displayName ? { displayName: registration.displayName } : {}),
     }),
   });
@@ -1007,11 +1013,7 @@ async function registerRelayBinding({ runtimeConfig, fetchImpl, logger }) {
           : registerResult.status >= 500
             ? 'transport'
             : 'config';
-    const publicMessage = errorCode === 'agent_code_conflict'
-      ? 'relay agent code already exists; reuse its appToken or choose a different registration.agentCode'
-      : errorCode === 'agent_code_mismatch'
-        ? 'configured relay agent code does not match the provided appToken'
-        : 'relay registration failed';
+    const publicMessage = 'relay registration failed';
 
     throw createRuntimeBoundaryError({
       code: errorCode,
@@ -1022,14 +1024,7 @@ async function registerRelayBinding({ runtimeConfig, fetchImpl, logger }) {
       recoverable: registerResult.status >= 500,
       context: {
         accountId: runtimeConfig.accountId || null,
-        requestedAgentCode: normalizeClaworldText(
-          registerResult.body?.requestedAgentCode,
-          registration.agentCode || null,
-        ),
-        authenticatedAgentCode: normalizeClaworldText(registerResult.body?.authenticatedAgentCode, null),
-        authenticatedAddress: normalizeClaworldText(registerResult.body?.authenticatedAddress, null),
         conflictingAgentId: normalizeClaworldText(registerResult.body?.agent?.agentId, null),
-        conflictingAddress: normalizeClaworldText(registerResult.body?.agent?.address, null),
         appTokenConfigured: Boolean(resolveRuntimeAppToken(runtimeConfig)),
       },
     });
@@ -1085,67 +1080,30 @@ async function resolveRelayAgentSummary({
   fetchImpl,
   logger,
   agentId = null,
-  agentCode = null,
-  address = null,
 }) {
-  const requestedIdentity = normalizeRelayIdentityInput({
-    runtimeConfig,
-    agentId,
-    agentCode,
-    address,
-  });
+  const normalizedAgentId = normalizeClaworldText(agentId, null);
 
   try {
     const items = await fetchRelayAgents({ runtimeConfig, fetchImpl, logger });
     const match = items
-      .map((item) => buildRelayAgentSummary(item, runtimeConfig))
-      .find((item) => {
-        if (requestedIdentity.agentId && item.agentId === requestedIdentity.agentId) return true;
-        if (requestedIdentity.agentCode && item.agentCode === requestedIdentity.agentCode) return true;
-        if (requestedIdentity.address && item.address === requestedIdentity.address) return true;
-        if (requestedIdentity.relayLocalCode && item.relayLocalCode === requestedIdentity.relayLocalCode) return true;
-        return false;
-      }) || null;
+      .map((item) => buildRelayAgentSummary(item))
+      .find((item) => normalizedAgentId && item.agentId === normalizedAgentId) || null;
 
     if (match) {
       return {
         ...match,
         resolved: true,
-        resolutionSource: requestedIdentity.agentId && match.agentId === requestedIdentity.agentId
-          ? 'agentId'
-          : requestedIdentity.agentCode && match.agentCode === requestedIdentity.agentCode
-            ? 'agentCode'
-            : requestedIdentity.address && match.address === requestedIdentity.address
-              ? 'address'
-              : 'relayLocalCode',
+        resolutionSource: 'agentId',
       };
     }
   } catch {
     // Fallback below keeps pairing/send tools usable even when lookup fails.
   }
 
-  const canInferFallbackAgentCode = Boolean(
-    requestedIdentity.agentCode
-    || requestedIdentity.address
-    || requestedIdentity.relayLocalCode,
-  );
-  const fallbackAgentCode = requestedIdentity.agentCode
-    || (canInferFallbackAgentCode ? buildCanonicalRelayAgentCode(runtimeConfig.localAgent?.agentCode, runtimeConfig) : null)
-    || (canInferFallbackAgentCode ? buildCanonicalRelayAgentCode(runtimeConfig.accountId, runtimeConfig) : null);
-  const parsedFallbackAgentCode = parseCanonicalRelayAgentCode(fallbackAgentCode);
-
   return {
-    agentId: requestedIdentity.agentId,
-    agentCode: fallbackAgentCode,
-    relayLocalCode: requestedIdentity.relayLocalCode
-      || parsedFallbackAgentCode?.relayLocalCode
-      || normalizeRelayLocalAgentCode(runtimeConfig.localAgent?.agentCode, null)
-      || null,
-    domain: requestedIdentity.domain
-      || parsedFallbackAgentCode?.domain
-      || normalizeRelayDomainName(inferRelayDomain(runtimeConfig), null),
-    address: requestedIdentity.address || fallbackAgentCode || null,
-    displayName: normalizeClaworldText(runtimeConfig.localAgent?.displayName, null),
+    agentId: normalizedAgentId,
+    displayName: normalizeClaworldText(runtimeConfig.registration?.displayName, normalizeClaworldText(runtimeConfig.localAgent?.displayName, null)),
+    publicIdentity: null,
     discoverable: null,
     contactable: null,
     online: null,
@@ -1158,10 +1116,6 @@ async function ensureAgentPairing({ runtimeConfig, fetchImpl, logger }) {
   const binding = await ensureRelayBinding({ runtimeConfig, fetchImpl, logger });
   const pairedRuntimeConfig = binding.runtimeConfig;
   const relayAgentId = normalizeClaworldText(pairedRuntimeConfig.relay?.agentId, null);
-  const relayAgentCode = normalizeRelayLocalAgentCode(
-    pairedRuntimeConfig.localAgent?.agentCode,
-    normalizeRelayLocalAgentCode(pairedRuntimeConfig.accountId, null),
-  );
 
   if (!relayAgentId) {
     return {
@@ -1174,7 +1128,6 @@ async function ensureAgentPairing({ runtimeConfig, fetchImpl, logger }) {
         fetchImpl,
         logger,
         agentId: relayAgentId,
-        agentCode: relayAgentCode,
       }),
     };
   }
@@ -1184,14 +1137,13 @@ async function ensureAgentPairing({ runtimeConfig, fetchImpl, logger }) {
     reason: null,
     bindingSource: binding.bindingSource,
     runtimeConfig: pairedRuntimeConfig,
-    relayAgent: await resolveRelayAgentSummary({
-      runtimeConfig: pairedRuntimeConfig,
-      fetchImpl,
-      logger,
-      agentId: relayAgentId,
-      agentCode: relayAgentCode,
-    }),
-  };
+      relayAgent: await resolveRelayAgentSummary({
+        runtimeConfig: pairedRuntimeConfig,
+        fetchImpl,
+        logger,
+        agentId: relayAgentId,
+      }),
+    };
 }
 
 async function fetchPostSetupWorldDirectory({ cfg, accountId, runtimeConfig, limit = null, sort = null, page = null, fetchImpl, logger }) {
@@ -1248,7 +1200,7 @@ async function ensureRelayBinding({ runtimeConfig, fetchImpl, logger }) {
     serverUrl: normalizedRuntimeConfig.serverUrl,
     appTokenConfigured: Boolean(appToken),
     registrationEnabled: registration.enabled,
-    agentCode: registration.agentCode || null,
+    displayName: registration.displayName || null,
     hasRelayAgentId: Boolean(normalizedRuntimeConfig.relay?.agentId),
   });
 
@@ -1273,10 +1225,12 @@ function buildDeliveryInboundEnvelope({
   incomingText,
   contextText = null,
   commandText = null,
+  timestamp = null,
   deliveryId,
   sessionKey,
   worldId = null,
   conversationKey = null,
+  untrustedContext = [],
 }) {
   const envelopeOptions = runtime?.channel?.reply?.resolveEnvelopeFormatOptions
     ? runtime.channel.reply.resolveEnvelopeFormatOptions(currentCfg)
@@ -1286,37 +1240,43 @@ function buildDeliveryInboundEnvelope({
     String(incomingText || '').trim(),
   ].filter(Boolean).join('\n\n');
   const remoteLabel = String(remoteIdentity || 'unknown-peer').trim() || 'unknown-peer';
-  const systemLines = [
+  const rawBody = String(incomingText || '').trim();
+  const normalizedCommandText = String(commandText || '').trim();
+  const commandBody = normalizedCommandText || rawBody;
+  const bodyForAgent = bodyText || rawBody;
+  const contextLines = mergeUntrustedContextLines([
     `[claworld peer ${remoteLabel}]`,
     ...(worldId ? [`[claworld world ${worldId}]`] : []),
     ...(conversationKey ? [`[claworld conversation ${conversationKey}]`] : []),
     `[claworld session ${sessionKey}]`,
     `[claworld delivery ${deliveryId}]`,
-  ];
-  const rawBody = `${bodyText}\n\n${systemLines.join('\n')}`;
-  const normalizedCommandText = String(commandText || '').trim();
-  const commandBody = normalizedCommandText || rawBody;
+  ], untrustedContext);
+  const envelopeTimestamp = Number.isFinite(timestamp) ? new Date(timestamp) : new Date();
 
   if (runtime?.channel?.reply?.formatAgentEnvelope) {
     return {
       Body: runtime.channel.reply.formatAgentEnvelope({
         channel: 'Claworld',
         from: remoteLabel,
-        timestamp: new Date(),
+        timestamp: envelopeTimestamp,
         envelope: envelopeOptions,
-        body: rawBody,
+        body: bodyForAgent,
       }),
       RawBody: rawBody,
       CommandBody: commandBody,
-      ContextLines: systemLines,
+      BodyForAgent: bodyForAgent,
+      BodyForCommands: commandBody,
+      UntrustedContext: contextLines,
     };
   }
 
   return {
-    Body: `${remoteLabel}: ${rawBody}`,
+    Body: `${remoteLabel}: ${bodyForAgent}`,
     RawBody: rawBody,
     CommandBody: commandBody,
-    ContextLines: systemLines,
+    BodyForAgent: bodyForAgent,
+    BodyForCommands: commandBody,
+    UntrustedContext: contextLines,
   };
 }
 
@@ -1678,15 +1638,14 @@ async function maybeBridgeRuntimeDelivery({
     : {};
   const deliveryId = resolveNormalizedText(delivery.deliveryId, null);
   const sessionKey = resolveNormalizedText(delivery.sessionKey, null);
-  const incomingText = resolveNormalizedText(payload.text, null);
-  const contextText = null;
+  const contextText = resolveNormalizedText(payload.contextText, null);
+  const incomingText = resolveNormalizedText(
+    payload.commandText,
+    contextText ? null : resolveNormalizedText(payload.text, null),
+  );
+  const commandText = resolveNormalizedText(payload.commandText, incomingText);
   const fromAgentId = resolveNormalizedText(metadata.fromAgentId, null);
-  const remoteAddress = resolveNormalizedText(metadata.fromAddress, null)
-    || resolveRelayAddress(fromAgentId || '', runtimeConfig)
-    || fromAgentId
-    || 'unknown-peer';
-  const remoteRouteIdentity = resolveRelayAddress(fromAgentId || '', runtimeConfig)
-    || remoteAddress;
+  const remoteIdentity = fromAgentId || 'unknown-peer';
 
   if (
     !runtime?.channel?.reply?.finalizeInboundContext
@@ -1699,11 +1658,12 @@ async function maybeBridgeRuntimeDelivery({
     });
     return { skipped: true, reason: 'missing_runtime_bridge_hooks' };
   }
-  if (!deliveryId || !sessionKey || !incomingText) {
+  if (!deliveryId || !sessionKey || (!incomingText && !contextText)) {
     logger.warn?.(`[claworld:${runtimeAccountId}] skipping delivery bridge: missing delivery payload`, {
       deliveryId,
       sessionKey,
       hasIncomingText: Boolean(incomingText),
+      hasContextText: Boolean(contextText),
     });
     return { skipped: true, reason: 'missing_delivery_payload' };
   }
@@ -1716,48 +1676,51 @@ async function maybeBridgeRuntimeDelivery({
   const worldId = resolveDeliveryWorldId(delivery);
   const commandAuthorized = shouldAuthorizeBridgedCommand({
     runtimeConfig,
-    incomingText,
+    incomingText: commandText || incomingText,
   });
-  const { Body, RawBody, CommandBody, ContextLines } = buildDeliveryInboundEnvelope({
+  const inboundTimestamp = resolveBridgeDeliveryTimestampMs({ delivery, metadata });
+  const { Body, RawBody, CommandBody, BodyForAgent, BodyForCommands, UntrustedContext } = buildDeliveryInboundEnvelope({
     runtime,
     currentCfg,
-    remoteIdentity: remoteAddress,
+    remoteIdentity,
     incomingText,
     contextText,
-    commandText: incomingText,
+    commandText,
+    timestamp: inboundTimestamp,
     deliveryId,
     sessionKey,
     worldId,
     conversationKey: metadata.conversationKey || null,
+    untrustedContext: payload.untrustedContext,
   });
-  const localAddress = resolveRelayAddress(runtimeConfig.accountId || '', runtimeConfig);
+  const localIdentity = normalizeClaworldText(runtimeConfig.relay?.agentId, runtimeConfig.accountId);
   const inboundCtx = runtime.channel.reply.finalizeInboundContext({
     Body,
     RawBody,
     CommandBody,
-    BodyForAgent: RawBody,
-    BodyForCommands: CommandBody,
-    From: `claworld:${remoteRouteIdentity}`,
-    To: localAddress ? `claworld:${localAddress}` : `claworld:${runtimeConfig.accountId}`,
+    BodyForAgent,
+    BodyForCommands,
+    From: `claworld:${remoteIdentity}`,
+    To: `claworld:${localIdentity}`,
     SessionKey: sessionKey,
     AccountId: runtimeConfig.accountId,
     OriginatingChannel: 'claworld',
-    OriginatingFrom: remoteRouteIdentity,
-    OriginatingTo: remoteRouteIdentity,
+    OriginatingFrom: remoteIdentity,
+    OriginatingTo: remoteIdentity,
     ChatType: 'direct',
-    SenderName: remoteAddress,
-    SenderId: remoteRouteIdentity,
+    SenderName: remoteIdentity,
+    SenderId: remoteIdentity,
     MessageId: deliveryId,
     Provider: 'claworld',
     Surface: 'claworld',
-    ConversationLabel: remoteAddress,
-    Timestamp: Date.now(),
+    ConversationLabel: remoteIdentity,
+    Timestamp: inboundTimestamp,
     MessageSid: deliveryId,
     WasMentioned: false,
     CommandAuthorized: commandAuthorized,
     RelayDeliveryId: deliveryId,
     RelayFromAgentId: fromAgentId,
-    UntrustedContext: ContextLines,
+    UntrustedContext,
   });
   const localAgentId = resolveBoundLocalAgentId({
     cfg: currentCfg,
@@ -1788,7 +1751,7 @@ async function maybeBridgeRuntimeDelivery({
     deliveryId,
     sessionKey,
     localAgentId,
-    remoteIdentity: remoteAddress,
+    remoteIdentity,
     routeStatus: routed?.status || null,
     bodyPreview: String(Body || '').slice(0, 240),
     rawBodyPreview: String(RawBody || '').slice(0, 240),
@@ -1796,6 +1759,23 @@ async function maybeBridgeRuntimeDelivery({
     commandAuthorized,
   });
 
+  try {
+    if (typeof relayClient?.sendAcceptedAndWaitForAck === 'function') {
+      await relayClient.sendAcceptedAndWaitForAck({
+        deliveryId,
+        sessionKey,
+        source: 'runtime_dispatch',
+      });
+    }
+  } catch (error) {
+    logger.warn?.(`[claworld:${runtimeAccountId}] delivery acceptance acknowledgement failed`, {
+      deliveryId,
+      sessionKey,
+      localAgentId,
+      error: error?.message || String(error),
+    });
+  }
+
   let {
     dispatchResult,
     replied,
@@ -2349,9 +2329,9 @@ export function createClaworldChannelPlugin({
     },
     agentPrompt: {
       messageToolHints: () => [
-        '- Claworld targets are canonical identity handles like `alice@robin`.',
+        '- Claworld message targets are canonical `agentId` values such as `agt_xxx`.',
         '- Omit `target` to keep replying inside the current A2A session when the runtime already inferred the peer.',
-        '- Use explicit targets like `user:alice@robin` when you want to open a new relay session to another remote OpenClaw agent.',
+        '- Resolve public identity like `displayName#code` to `agentId` before opening a new relay session to another agent.',
       ],
     },
     reload: { configPrefixes: ['channels.claworld'] },
@@ -2383,19 +2363,18 @@ export function createClaworldChannelPlugin({
         looksLikeId: (raw, normalized) => {
           const value = String(normalized || raw || '').trim();
           if (!value) return false;
-          if (value.includes('@')) return RELAY_CANONICAL_AGENT_CODE_PATTERN.test(value);
-          return /^[a-z0-9._:+~-]+$/i.test(value) || /^agt_[a-z0-9_-]+$/i.test(value);
+          return /^agt_[a-z0-9_-]+$/i.test(value);
         },
-        hint: '<agent@relay-domain|agentId>',
+        hint: '<agentId>',
       },
     },
     directory: {
       self: async ({ cfg, accountId } = {}) => {
         const account = inspectClaworldChannelAccount(cfg || {}, accountId || null);
-        const address = resolveRelayAddress(account?.accountId || '', account || {});
-        if (!account?.configured || !address) return null;
+        const agentId = normalizeClaworldText(account?.relay?.agentId, null);
+        if (!account?.configured || !agentId) return null;
         return {
-          id: address,
+          id: agentId,
           name: account.accountId,
           handle: account.accountId,
         };
@@ -2478,8 +2457,6 @@ export function createClaworldChannelPlugin({
           fetchImpl,
           logger,
           agentId: context.agentId || context.targetAgentId || null,
-          agentCode: context.agentCode || context.targetAgentCode || null,
-          address: context.address || null,
         }),
       },
       social: {
@@ -2488,7 +2465,7 @@ export function createClaworldChannelPlugin({
           return createFriendRequest({
             runtimeConfig: resolvedContext.runtimeConfig,
             fromAgentId: resolvedContext.agentId || null,
-            toAddress: context.toAddress || null,
+            targetAgentId: context.targetAgentId || null,
             message: context.message || null,
             metadata: context.metadata || {},
             fetchImpl,
@@ -2578,6 +2555,25 @@ export function createClaworldChannelPlugin({
           });
         },
       },
+      profile: {
+        getPublicIdentity: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return fetchPublicIdentity({
+            runtimeConfig: resolvedContext.runtimeConfig,
+            agentId: resolvedContext.agentId || null,
+            fetchImpl,
+          });
+        },
+        updatePublicIdentity: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return updatePublicIdentity({
+            runtimeConfig: resolvedContext.runtimeConfig,
+            agentId: resolvedContext.agentId || null,
+            displayName: context.displayName || null,
+            fetchImpl,
+          });
+        },
+      },
       postSetup: {
         fetchWorldDirectory: async (context = {}) => {
           const resolvedContext = await resolveBoundRuntimeContext(context);
@@ -2686,7 +2682,7 @@ export function createClaworldChannelPlugin({
             agentId: resolvedContext.agentId || null,
             displayName: context.displayName || null,
             worldContextText: context.worldContextText || null,
-            enabled: context.enabled === true,
+            enabled: typeof context.enabled === 'boolean' ? context.enabled : true,
             fetchImpl,
             logger,
           });
@@ -2728,6 +2724,25 @@ export function createClaworldChannelPlugin({
       results,
       demo,
       productShell: {
+        profile: {
+          getPublicIdentity: async (context = {}) => {
+            const resolvedContext = await resolveBoundRuntimeContext(context);
+            return fetchPublicIdentity({
+              runtimeConfig: resolvedContext.runtimeConfig || null,
+              agentId: resolvedContext.agentId || null,
+              fetchImpl,
+            });
+          },
+          updatePublicIdentity: async (context = {}) => {
+            const resolvedContext = await resolveBoundRuntimeContext(context);
+            return updatePublicIdentity({
+              runtimeConfig: resolvedContext.runtimeConfig || null,
+              agentId: resolvedContext.agentId || null,
+              displayName: context.displayName || null,
+              fetchImpl,
+            });
+          },
+        },
         fetchWorldDirectory: async (context = {}) => {
           const resolvedContext = await resolveBoundRuntimeContext(context);
           return fetchPostSetupWorldDirectory({
@@ -2868,14 +2883,14 @@ export function createClaworldChannelPlugin({
         moderation: {
           createWorld: async (context = {}) => {
             const resolvedContext = await resolveBoundRuntimeContext(context);
-          return createModeratedWorld({
+            return createModeratedWorld({
               cfg: resolvedContext.cfg || {},
               accountId: resolvedContext.accountId || null,
               runtimeConfig: resolvedContext.runtimeConfig || null,
               agentId: resolvedContext.agentId || null,
               displayName: context.displayName || null,
               worldContextText: context.worldContextText || null,
-              enabled: context.enabled === true,
+              enabled: typeof context.enabled === 'boolean' ? context.enabled : true,
               fetchImpl,
               logger,
             });