@xfxstudio/claworld 0.2.9 → 0.2.10-beta.0

package/src/openclaw/plugin/onboarding.js

@@ -7,27 +7,16 @@ import {
   resolveClaworldManagedRuntimeOptions,
 } from './managed-config.js';
 import {
-  LOCAL_AGENT_BOOTSTRAP_SCHEMA,
   defaultClaworldAccountId,
   inspectClaworldChannelAccount,
   listClaworldAccountIds,
 } from './config-schema.js';
-import { parseAgentHandle } from '../../lib/agent-address.js';
 import {
   buildManagedOnboardingStatus as buildClaworldOnboardingStatus,
   inspectManagedClaworldInstall,
   seedManagedWorkspace as ensureManagedWorkspaceSeed,
 } from '../installer/core.js';
 
-const LOCAL_AGENT_CODE_REGEX = new RegExp(
-  LOCAL_AGENT_BOOTSTRAP_SCHEMA?.properties?.agentCode?.pattern || '^[A-Za-z0-9._:+~-]+$',
-  'i',
-);
-
-function isCanonicalAgentHandle(value) {
-  return Boolean(parseAgentHandle(value)?.canonical);
-}
-
 function collectUnsupportedSetupFlags(input = {}) {
   const unsupported = [];
   const flagMap = [
@@ -69,7 +58,7 @@ function validateClaworldSetupInput({ cfg = {}, accountId = null, input = {} } =
   const unsupportedFlags = collectUnsupportedSetupFlags(input);
   if (unsupportedFlags.length > 0) {
     return (
-      'Claworld setup only supports --name, --http-url/--url, --app-token, and --code. ' +
+      'Claworld setup only supports --name, --http-url/--url, and --app-token. ' +
       `Unsupported flag(s): ${unsupportedFlags.join(', ')}.`
     );
   }
@@ -92,24 +81,15 @@ function validateClaworldSetupInput({ cfg = {}, accountId = null, input = {} } =
     }
   }
 
-  const explicitRegistrationAgentCode = normalizeText(input.code, null);
-  const existingRegistrationAgentCode = normalizeText(
-    inspected?.registration?.agentCode,
-    normalizeText(inspected?.localAgent?.agentCode, null),
+  const registrationDisplayName = normalizeText(
+    input.name,
+    normalizeText(
+      inspected?.registration?.displayName,
+      normalizeText(inspected?.localAgent?.displayName, null),
+    ),
   );
-  const registrationAgentCode = explicitRegistrationAgentCode
-    || (isCanonicalAgentHandle(existingRegistrationAgentCode) ? existingRegistrationAgentCode : null);
-  if (!appToken && !explicitRegistrationAgentCode && existingRegistrationAgentCode && !isCanonicalAgentHandle(existingRegistrationAgentCode)) {
-    return 'Existing Claworld registration.agentCode is legacy/raw. Re-run setup with --code <local@namespace> so the namespace stays explicit.';
-  }
-  if (!appToken && !registrationAgentCode) {
-    return 'Claworld identity handle is required unless you already have an appToken. Use --code <local@namespace> or --app-token <token>.';
-  }
-  if (!appToken && explicitRegistrationAgentCode && !LOCAL_AGENT_CODE_REGEX.test(explicitRegistrationAgentCode)) {
-    return 'Claworld identity handle must match ^[A-Za-z0-9._:+~-]+(?:@[A-Za-z0-9._:+~-]+)?$.';
-  }
-  if (!appToken && explicitRegistrationAgentCode && !isCanonicalAgentHandle(explicitRegistrationAgentCode)) {
-    return 'Claworld identity handle must use canonical local@namespace syntax (for example "xiaofafa@robin").';
+  if (!appToken && !registrationDisplayName) {
+    return 'Claworld public display name is required unless you already have an appToken. Use --name <display-name> or --app-token <token>.';
   }
 
   return null;
@@ -124,12 +104,12 @@ function currentManagedIdentityInput({ cfg = {}, accountId = null } = {}) {
     };
   }
 
-  const currentCode = normalizeText(
-    inspected?.registration?.agentCode,
-    normalizeText(inspected?.localAgent?.agentCode, null),
+  const currentDisplayName = normalizeText(
+    inspected?.registration?.displayName,
+    normalizeText(inspected?.localAgent?.displayName, null),
   );
-  return isCanonicalAgentHandle(currentCode)
-    ? { code: currentCode }
+  return currentDisplayName
+    ? { name: currentDisplayName }
     : {};
 }
 
@@ -139,18 +119,18 @@ async function collectManagedIdentityInput({ cfg = {}, prompter, accountId = nul
     return currentInput;
   }
 
-  const code = await prompter.text({
-    message: 'Choose a unique Claworld identity handle',
-    initialValue: currentInput.code || '',
-    placeholder: 'xiaofafa@robin',
+  const name = await prompter.text({
+    message: 'Choose the public display name to bootstrap this Claworld agent',
+    initialValue: currentInput.name || '',
+    placeholder: 'Claworld Agent',
     validate: (value) => {
-      const message = validateClaworldSetupInput({ input: { code: value } });
+      const message = validateClaworldSetupInput({ input: { name: value } });
       return message || undefined;
     },
   });
 
   return {
-    code,
+    name,
   };
 }
 
@@ -207,8 +187,8 @@ async function applyManagedOnboardingConfig({
   const noteLines = [
     `Bound local agent/account: ${managedOptions.agentId}`,
     `Remote backend: ${managedOptions.serverUrl}`,
-    managedOptions.registrationAgentCode
-      ? `Bootstrap mode: registration (${managedOptions.registrationAgentCode})`
+    managedOptions.registrationDisplayName
+      ? `Bootstrap mode: registration (${managedOptions.registrationDisplayName})`
       : 'Bootstrap mode: appToken/manual binding',
     managedOptions.manageWorkspace
       ? 'This flow refreshes plugin-side config and the dedicated claworld workspace contract. It does not start a backend service.'

package/src/openclaw/plugin/register.js

@@ -18,6 +18,11 @@ import {
   logRuntimeBoundary,
   normalizeRuntimeBoundaryError,
 } from '../../lib/runtime-errors.js';
+import {
+  normalizeBackendFieldError,
+  normalizeBackendMissingField,
+  normalizeBackendPublicIdentity,
+} from '../runtime/backend-error-context.js';
 
 const INTERNAL_REQUESTER_SESSION_KEY_PARAM = '__claworldRequesterSessionKey';
 
@@ -52,14 +57,30 @@ function buildPublicToolErrorExtras(error) {
   const backendCode = normalizeText(context.backendCode, null);
   const backendMessage = normalizeText(context.backendMessage, null);
   const fieldErrors = Array.isArray(context.fieldErrors)
-    ? context.fieldErrors.map((fieldError) => normalizePublicFieldError(fieldError)).filter(Boolean)
+    ? context.fieldErrors
+      .map((fieldError) => normalizeBackendFieldError(fieldError) || normalizePublicFieldError(fieldError))
+      .filter(Boolean)
+    : [];
+  const requiredAction = normalizeText(context.requiredAction, null);
+  const nextAction = normalizeText(context.nextAction, null);
+  const nextTool = normalizeText(context.nextTool, null);
+  const missingFields = Array.isArray(context.missingFields)
+    ? context.missingFields
+      .map((field) => normalizeBackendMissingField(field))
+      .filter(Boolean)
     : [];
+  const publicIdentity = normalizeBackendPublicIdentity(context.publicIdentity);
 
   const extra = {
     ...(Number.isInteger(httpStatus) && httpStatus > 0 ? { httpStatus } : {}),
     ...(backendCode ? { backendCode } : {}),
     ...(backendMessage ? { backendMessage } : {}),
     ...(fieldErrors.length > 0 ? { fieldErrors } : {}),
+    ...(requiredAction ? { requiredAction } : {}),
+    ...(nextAction ? { nextAction } : {}),
+    ...(nextTool ? { nextTool } : {}),
+    ...(missingFields.length > 0 ? { missingFields } : {}),
+    ...(publicIdentity ? { publicIdentity } : {}),
   };
 
   return Object.keys(extra).length > 0 ? extra : null;
@@ -553,7 +574,7 @@ function buildRegisteredTools(api, plugin) {
           ...context,
           displayName: params.displayName,
           worldContextText: params.worldContextText,
-          enabled: params.enabled === true,
+          enabled: typeof params.enabled === 'boolean' ? params.enabled : true,
         });
         return buildToolResult(projectToolCreateWorldResponse(payload, { accountId: context.accountId }));
       },
@@ -1009,10 +1030,6 @@ function buildRegisteredTools(api, plugin) {
                 description: 'Optional peer agentId related to the issue.',
                 examples: ['agt_runtime_candidate'],
               }),
-              targetAgentCode: stringParam({
-                description: 'Optional compatibility agentCode for the peer.',
-                examples: ['runtimecandidate@relay.local'],
-              }),
               tags: arrayParam({
                 description: 'Short labels used for moderation and triage filtering.',
                 maxItems: 10,
@@ -1110,6 +1127,15 @@ function buildRegisteredTools(api, plugin) {
           accountId,
           runtimeConfig,
         });
+        const pairedAgentId = payload.runtimeConfig?.relay?.agentId || payload.relayAgent?.agentId || null;
+        const publicIdentity = pairedAgentId
+          ? await plugin.runtime.productShell.profile.getPublicIdentity({
+            cfg,
+            accountId,
+            runtimeConfig,
+            agentId: pairedAgentId,
+          })
+          : null;
         return buildToolResult({
           status: payload.status,
           reason: payload.reason || null,
@@ -1117,17 +1143,90 @@ function buildRegisteredTools(api, plugin) {
           bindingSource: payload.bindingSource || null,
           relay: {
             agentId: payload.runtimeConfig?.relay?.agentId || payload.relayAgent?.agentId || null,
-            agentCode: payload.relayAgent?.agentCode || null,
-            relayLocalCode: payload.relayAgent?.relayLocalCode || null,
-            address: payload.relayAgent?.address || null,
-            domain: payload.relayAgent?.domain || null,
             displayName: payload.relayAgent?.displayName || null,
             discoverable: payload.relayAgent?.discoverable ?? null,
             contactable: payload.relayAgent?.contactable ?? null,
             online: payload.relayAgent?.online ?? null,
             resolved: payload.relayAgent?.resolved ?? null,
           },
+          publicIdentity: publicIdentity
+            ? {
+              status: publicIdentity.status || null,
+              ready: publicIdentity.ready ?? null,
+              displayIdentity: publicIdentity.publicIdentity?.displayIdentity || null,
+              displayName: publicIdentity.publicIdentity?.displayName || null,
+              code: publicIdentity.publicIdentity?.code || null,
+              nextAction: publicIdentity.nextAction || null,
+              nextTool: publicIdentity.nextTool || null,
+              missingFields: Array.isArray(publicIdentity.missingFields) ? publicIdentity.missingFields : [],
+              recommendedDisplayName: publicIdentity.recommendedDisplayName || null,
+              feedbackSummary: publicIdentity.feedbackSummary && typeof publicIdentity.feedbackSummary === 'object'
+                ? {
+                  totalLikesReceived: Number(publicIdentity.feedbackSummary.totalLikesReceived || 0),
+                  totalDislikesReceived: Number(publicIdentity.feedbackSummary.totalDislikesReceived || 0),
+                  totalLikesGiven: Number(publicIdentity.feedbackSummary.totalLikesGiven || 0),
+                  totalDislikesGiven: Number(publicIdentity.feedbackSummary.totalDislikesGiven || 0),
+                }
+                : null,
+            }
+            : null,
+        });
+      },
+    },
+    {
+      name: 'claworld_get_public_identity',
+      label: 'Claworld Get Public Identity',
+      description: 'Read the current public identity state for the paired Claworld agent. Use this before world join or request-chat if you need to confirm whether public naming is complete.',
+      metadata: buildToolMetadata({
+        category: 'bootstrap',
+        usageNotes: [
+          'Use when pair_agent indicates public identity is still pending.',
+          'Use before requesting a public-name confirmation from the user.',
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Read the current public identity state for one Claworld account.',
+        required: ['accountId'],
+        properties: {
+          accountId: accountIdProperty,
+        },
+      }),
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.runtime.productShell.profile.getPublicIdentity(context);
+        return buildToolResult(payload);
+      },
+    },
+    {
+      name: 'claworld_update_public_identity',
+      label: 'Claworld Update Public Identity',
+      description: 'Set or update the public display name for the paired Claworld agent. On first setup, the backend will generate a stable unique code and return the final displayName#code identity.',
+      metadata: buildToolMetadata({
+        category: 'bootstrap',
+        usageNotes: [
+          'Use after the user confirms a public-facing name.',
+          'On first setup, this generates the stable public code and completes identity readiness.',
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Update the public display name for one Claworld account.',
+        required: ['accountId', 'displayName'],
+        properties: {
+          accountId: accountIdProperty,
+          displayName: stringParam({
+            description: 'Public-facing display name. # is reserved and must not appear here.',
+            minLength: 1,
+            examples: ['Moza', '小发发'],
+          }),
+        },
+      }),
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.runtime.productShell.profile.updatePublicIdentity({
+          ...context,
+          displayName: params.displayName,
         });
+        return buildToolResult(payload);
       },
     },
   ].map((tool) => ({

package/src/openclaw/plugin/relay-client.js

@@ -1,5 +1,6 @@
 import { EventEmitter } from 'events';
 import WebSocket from 'ws';
+import { v4 as uuidv4 } from 'uuid';
 import { resolveClaworldRuntimeConfig } from './config-schema.js';
 import { buildRuntimeAuthHeaders } from './account-identity.js';
 import { createRelayEventProtocol } from '../protocol/relay-event-protocol.js';
@@ -43,6 +44,9 @@ function buildInboundEnvelope(message = {}) {
     eventType: data.eventType || 'delivery',
     deliveryId: data.deliveryId || null,
     sessionKey: data.sessionKey || null,
+    createdAt: data.createdAt || null,
+    updatedAt: data.updatedAt || null,
+    turnCreatedAt: data.turnCreatedAt || null,
     payload: data.payload && typeof data.payload === 'object' && !Array.isArray(data.payload)
       ? { ...data.payload }
       : {},
@@ -56,6 +60,10 @@ function normalizeOptionalText(value) {
   return normalized || null;
 }
 
+function resolveClientMessageId(value = null) {
+  return normalizeOptionalText(value) || `cmsg_${uuidv4()}`;
+}
+
 function buildReplyAckTimeoutError({ deliveryId, timeoutMs, context = {} } = {}) {
   return createRuntimeBoundaryError({
     code: 'relay_reply_ack_timeout',
@@ -68,6 +76,18 @@ function buildReplyAckTimeoutError({ deliveryId, timeoutMs, context = {} } = {})
   });
 }
 
+function buildAcceptedAckTimeoutError({ deliveryId, timeoutMs, context = {} } = {}) {
+  return createRuntimeBoundaryError({
+    code: 'relay_delivery_accept_ack_timeout',
+    category: 'transport',
+    status: 504,
+    message: `timed out waiting for relay delivery acceptance acknowledgement for ${deliveryId || 'unknown-delivery'} after ${timeoutMs}ms`,
+    publicMessage: 'relay delivery acceptance acknowledgement timed out',
+    recoverable: true,
+    context,
+  });
+}
+
 function buildReplyFallbackError({
   deliveryId,
   status,
@@ -655,6 +675,34 @@ export class ClaworldRelayClient extends EventEmitter {
     this.send({ type: 'heartbeat' });
   }
 
+  sendAccepted({ deliveryId, sessionKey, source = 'runtime_dispatch' } = {}) {
+    const normalizedDeliveryId = normalizeOptionalText(deliveryId);
+    if (!normalizedDeliveryId) {
+      throw createRuntimeBoundaryError({
+        code: 'relay_delivery_id_required',
+        category: 'input',
+        status: 400,
+        message: 'deliveryId is required to acknowledge relay delivery acceptance',
+        publicMessage: 'deliveryId is required',
+        recoverable: true,
+      });
+    }
+    const envelope = {
+      deliveryId: normalizedDeliveryId,
+      sessionKey: normalizeOptionalText(sessionKey) || null,
+      source: normalizeOptionalText(source) || 'runtime_dispatch',
+    };
+    this.send({
+      type: 'accepted',
+      deliveryId: envelope.deliveryId,
+      sessionKey: envelope.sessionKey,
+      payload: {
+        source: envelope.source,
+      },
+    });
+    return envelope;
+  }
+
   sendReply({ deliveryId, sessionKey, replyText, source = 'subagent' } = {}) {
     const envelope = this.outbound.createReplyEnvelope({
       deliveryId,
@@ -791,6 +839,85 @@ export class ClaworldRelayClient extends EventEmitter {
     });
   }
 
+  waitForAcceptedAck({ deliveryId, timeoutMs = DEFAULT_REPLY_ACK_TIMEOUT_MS } = {}) {
+    const normalizedDeliveryId = normalizeOptionalText(deliveryId);
+    if (!normalizedDeliveryId) {
+      return Promise.reject(createRuntimeBoundaryError({
+        code: 'relay_delivery_id_required',
+        category: 'input',
+        status: 400,
+        message: 'deliveryId is required to wait for relay delivery acceptance acknowledgement',
+        publicMessage: 'deliveryId is required',
+        recoverable: true,
+      }));
+    }
+
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let timeout = null;
+
+      const cleanup = () => {
+        if (timeout) clearTimeout(timeout);
+        this.off('delivery.accepted', onAccepted);
+        this.off('disconnect', onDisconnect);
+        this.off('close', onDisconnect);
+      };
+
+      const settleResolve = (value) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve(value);
+      };
+
+      const settleReject = (error) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(error);
+      };
+
+      const onAccepted = (message = {}) => {
+        const acceptedDeliveryId = normalizeOptionalText(message?.data?.acceptedDeliveryId);
+        if (acceptedDeliveryId !== normalizedDeliveryId) return;
+        settleResolve(message);
+      };
+
+      const onDisconnect = (info = {}) => {
+        settleReject(createRuntimeBoundaryError({
+          code: 'relay_delivery_accept_ack_disconnected',
+          category: 'transport',
+          status: 502,
+          message: `relay websocket closed before delivery acceptance acknowledgement for ${normalizedDeliveryId}`,
+          publicMessage: 'relay websocket closed before delivery acceptance acknowledgement',
+          recoverable: true,
+          context: this.buildBoundaryContext({
+            stage: 'delivery_accept_ack_wait',
+            deliveryId: normalizedDeliveryId,
+            closeCode: info?.code ?? null,
+            closeReason: info?.reason || null,
+          }),
+        }));
+      };
+
+      this.on('delivery.accepted', onAccepted);
+      this.on('disconnect', onDisconnect);
+      this.on('close', onDisconnect);
+
+      timeout = setTimeout(() => {
+        settleReject(buildAcceptedAckTimeoutError({
+          deliveryId: normalizedDeliveryId,
+          timeoutMs,
+          context: this.buildBoundaryContext({
+            stage: 'delivery_accept_ack_wait',
+            deliveryId: normalizedDeliveryId,
+          }),
+        }));
+      }, timeoutMs);
+      if (typeof timeout.unref === 'function') timeout.unref();
+    });
+  }
+
   waitForKeepSilentAck({ deliveryId, timeoutMs = DEFAULT_REPLY_ACK_TIMEOUT_MS } = {}) {
     const normalizedDeliveryId = normalizeOptionalText(deliveryId);
     if (!normalizedDeliveryId) {
@@ -897,6 +1024,31 @@ export class ClaworldRelayClient extends EventEmitter {
     };
   }
 
+  async acceptDeliveryHttp({ deliveryId, sessionKey = null, source = 'runtime_dispatch' } = {}) {
+    const normalizedDeliveryId = normalizeOptionalText(deliveryId);
+    const result = await this.requestJson(`/v1/deliveries/${encodeURIComponent(normalizedDeliveryId)}/accepted`, {
+      method: 'POST',
+      headers: buildRuntimeAuthHeaders(this.runtimeConfig, { 'content-type': 'application/json' }),
+      body: JSON.stringify({
+        fromAgentId: this.boundAgentId,
+        sessionKey: normalizeOptionalText(sessionKey) || null,
+        source: normalizeOptionalText(source) || 'runtime_dispatch',
+      }),
+    }, {
+      code: 'relay_delivery_accept_fallback_failed',
+      message: 'failed to submit relay delivery acceptance fallback',
+      publicMessage: 'failed to submit relay delivery acceptance fallback',
+    });
+    return {
+      ...result,
+      envelope: {
+        deliveryId: normalizedDeliveryId,
+        sessionKey: normalizeOptionalText(sessionKey) || null,
+        source: normalizeOptionalText(source) || 'runtime_dispatch',
+      },
+    };
+  }
+
   async sendReplyAndWaitForAck({
     deliveryId,
     sessionKey,
@@ -984,6 +1136,75 @@ export class ClaworldRelayClient extends EventEmitter {
     }
   }
 
+  async sendAcceptedAndWaitForAck({
+    deliveryId,
+    sessionKey,
+    source = 'runtime_dispatch',
+    timeoutMs = DEFAULT_REPLY_ACK_TIMEOUT_MS,
+    httpFallback = true,
+  } = {}) {
+    const envelope = this.sendAccepted({
+      deliveryId,
+      sessionKey,
+      source,
+    });
+
+    try {
+      const ack = await this.waitForAcceptedAck({
+        deliveryId: envelope.deliveryId,
+        timeoutMs,
+      });
+      return {
+        ok: true,
+        envelope,
+        ack,
+        transport: 'websocket',
+        fallbackUsed: false,
+      };
+    } catch (error) {
+      if (!httpFallback) throw error;
+
+      this.logger.warn?.('[claworld:relay-client] delivery acceptance websocket acknowledgement failed; attempting HTTP fallback', {
+        accountId: this.runtimeConfig?.accountId || null,
+        agentId: this.boundAgentId,
+        deliveryId: envelope.deliveryId,
+        sessionKey: envelope.sessionKey,
+        error: error?.message || String(error),
+      });
+
+      const fallbackResult = await this.acceptDeliveryHttp({
+        deliveryId: envelope.deliveryId,
+        sessionKey: envelope.sessionKey,
+        source: envelope.source,
+      });
+
+      if (fallbackResult.status >= 200 && fallbackResult.status < 300) {
+        return {
+          ok: true,
+          envelope,
+          ack: {
+            event: 'delivery.accepted',
+            data: fallbackResult.body,
+          },
+          transport: 'http',
+          fallbackUsed: true,
+        };
+      }
+
+      throw buildReplyFallbackError({
+        deliveryId: envelope.deliveryId,
+        status: fallbackResult.status,
+        body: fallbackResult.body,
+        context: this.buildBoundaryContext({
+          stage: 'delivery_accept_fallback',
+          deliveryId: envelope.deliveryId,
+          sessionKey: envelope.sessionKey,
+          fallbackFrom: error?.code || error?.message || null,
+        }),
+      });
+    }
+  }
+
   async keepDeliverySilentHttp({ deliveryId, reason = null, source = 'openclaw-autochain' } = {}) {
     const normalizedDeliveryId = normalizeOptionalText(deliveryId);
     const result = await this.requestJson(`/v1/deliveries/${encodeURIComponent(normalizedDeliveryId)}/kept-silent`, {
@@ -1096,24 +1317,14 @@ export class ClaworldRelayClient extends EventEmitter {
     }
   }
 
-  async createChatRequest({ fromAgentId, toAddress, requestContext = {} } = {}) {
-    const target = await this.requestJson(`/v1/agents/resolve?address=${encodeURIComponent(toAddress)}`, {
-      method: 'GET',
-      headers: buildRuntimeAuthHeaders(this.runtimeConfig),
-    }, {
-      code: 'relay_target_resolve_failed',
-      message: 'failed to resolve relay target',
-      publicMessage: 'failed to resolve relay target',
-    });
-    if (target.status >= 400) return target;
-
+  async createChatRequest({ fromAgentId, targetAgentId, requestContext = {} } = {}) {
     const normalized = normalizeChatRequestInput({ requestContext, source: 'direct_lookup' });
     return await this.requestJson('/v1/chat-requests', {
       method: 'POST',
       headers: buildRuntimeAuthHeaders(this.runtimeConfig, { 'content-type': 'application/json' }),
       body: JSON.stringify({
         fromAgentId,
-        targetAgentId: target.body?.agentId || target.body?.id || null,
+        targetAgentId,
         kickoffBrief: normalized.kickoffBrief || null,
         openingMessage: normalized.openingMessage || null,
         worldId: normalized.conversation?.worldId || null,
@@ -1164,16 +1375,21 @@ export class ClaworldRelayClient extends EventEmitter {
     });
   }
 
-  async deliverMessage({ fromAgentId, toAddress, payload = {}, conversation = {} } = {}) {
-    return await this.requestJson('/v1/messages', {
+  async deliverMessage({ fromAgentId, targetAgentId, clientMessageId = null, payload = {}, conversation = {} } = {}) {
+    const resolvedClientMessageId = resolveClientMessageId(clientMessageId);
+    const result = await this.requestJson('/v1/messages', {
       method: 'POST',
       headers: buildRuntimeAuthHeaders(this.runtimeConfig, { 'content-type': 'application/json' }),
-      body: JSON.stringify({ fromAgentId, toAddress, payload, conversation }),
+      body: JSON.stringify({ fromAgentId, targetAgentId, clientMessageId: resolvedClientMessageId, payload, conversation }),
     }, {
       code: 'relay_message_delivery_failed',
       message: 'failed to deliver relay message',
       publicMessage: 'failed to deliver relay message',
     });
+    return {
+      ...result,
+      clientMessageId: resolvedClientMessageId,
+    };
   }
 
   waitFor(eventNameOrPredicate, timeoutMs = 8000) {
@@ -1201,7 +1417,7 @@ export class ClaworldRelayClient extends EventEmitter {
     });
   }
 
-  async establishConversation({ fromAgentId, toAddress, requestContext = {}, openingPayload = {} } = {}) {
+  async establishConversation({ fromAgentId, targetAgentId, requestContext = {}, openingPayload = {} } = {}) {
     const normalizedRequestContext = requestContext && typeof requestContext === 'object' && !Array.isArray(requestContext)
       ? { ...requestContext }
       : {};
@@ -1217,7 +1433,7 @@ export class ClaworldRelayClient extends EventEmitter {
 
     const requestResult = await this.createChatRequest({
       fromAgentId,
-      toAddress,
+      targetAgentId,
       requestContext: normalizedRequestContext,
     });
     if (requestResult.status !== 201) {