@xfxstudio/claworld 0.2.9 → 0.2.10-beta.1

package/src/product-shell/onboarding/onboarding-service.js

@@ -1,9 +1,9 @@
-import { randomUUID } from 'crypto';
 import {
   CLAWORLD_DOCTOR_COMMAND,
   CLAWORLD_INSTALLER_COMMAND,
   CLAWORLD_INSTALLER_PACKAGE_NAME,
   CLAWORLD_OPENCLAW_MIN_HOST_VERSION,
+  CLAWORLD_UNINSTALL_COMMAND,
   CLAWORLD_UPDATE_COMMAND,
 } from '../../openclaw/installer/constants.js';
 
@@ -55,10 +55,6 @@ function createInvalidActivationRequestError(fieldId, message) {
   return error;
 }
 
-function createHiddenActivationAgentCode() {
-  return `claworld_install_${randomUUID().replace(/-/g, '').slice(0, 20)}`;
-}
-
 function createActivatedResponse({ agent, appToken, created, bindingSource }) {
   return {
     status: 'activated',
@@ -66,7 +62,6 @@ function createActivatedResponse({ agent, appToken, created, bindingSource }) {
     bindingSource: normalizeText(bindingSource, null),
     agentId: normalizeText(agent?.agentId, null),
     appToken: normalizeText(appToken, null),
-    agentCode: null,
   };
 }
 
@@ -74,7 +69,6 @@ function validateActivationInput(input = {}) {
   const normalizedInput = input && typeof input === 'object' && !Array.isArray(input) ? input : {};
   const blockedFields = [
     ['agentId', 'dialog-first activation must not receive a user-provided agentId'],
-    ['agentCode', 'dialog-first activation must not receive a user-provided agentCode'],
     ['code', 'dialog-first activation must not receive a user-provided code'],
     ['appToken', 'dialog-first activation must not receive a user-provided appToken in the request body'],
   ];
@@ -91,19 +85,13 @@ function validateActivationInput(input = {}) {
 }
 
 function createActivatedAgent({ store, displayName }) {
-  for (let attempt = 0; attempt < 5; attempt += 1) {
-    try {
-      return store.createAgent({
-        agentCode: createHiddenActivationAgentCode(),
-        displayName,
-      });
-    } catch (error) {
-      if (error?.message === 'address already exists') continue;
-      throw error;
-    }
-  }
-
-  throw new Error('failed_to_generate_activation_identity');
+  return store.createAgent({
+    displayName,
+    publicIdentity: {
+      displayName,
+      status: 'pending',
+    },
+  });
 }
 
 export function createOnboardingService({ worldService, store = null } = {}) {
@@ -127,6 +115,7 @@ export function createOnboardingService({ worldService, store = null } = {}) {
             install: CLAWORLD_INSTALLER_COMMAND,
             doctor: CLAWORLD_DOCTOR_COMMAND,
             update: CLAWORLD_UPDATE_COMMAND,
+            uninstall: CLAWORLD_UNINSTALL_COMMAND,
           },
         },
         plugin: {
@@ -163,7 +152,7 @@ export function createOnboardingService({ worldService, store = null } = {}) {
           requiresUserCode: false,
           canonicalIdentityField: 'agentId',
           credentialField: 'appToken',
-          responseFields: ['status', 'agentId', 'appToken', 'agentCode'],
+          responseFields: ['status', 'agentId', 'appToken'],
         },
         verification: {
           statusRoute: '/plugins/claworld/status',
@@ -175,9 +164,9 @@ export function createOnboardingService({ worldService, store = null } = {}) {
           'installer validates OpenClaw availability and minimum host version',
           'installer verifies or installs the claworld OpenClaw plugin package',
           'installer writes or refreshes the managed claworld channel config and binds it to the local main agent by default',
-          'installer calls POST /v1/onboarding/activate to obtain agentId and appToken when reuse is not possible',
-          'installer persists the returned appToken into the managed claworld account config',
-          'installer reloads or starts the runtime and verifies the relay binding',
+          'installer reloads or starts the runtime and verifies the managed channel shape without requiring backend activation',
+          'first-run readiness goes through claworld_pair_agent and then claworld_update_public_identity',
+          'claworld_update_public_identity performs activation when needed and completes the public displayName#code identity',
           `ongoing lifecycle uses ${CLAWORLD_UPDATE_COMMAND} for tracked package updates plus managed repair, then ${CLAWORLD_DOCTOR_COMMAND} for health confirmation`,
         ],
         recommendedWorlds,
@@ -193,8 +182,9 @@ export function createOnboardingService({ worldService, store = null } = {}) {
         selectedWorld: selectedWorld ? { worldId: selectedWorld.worldId, displayName: selectedWorld.displayName } : null,
         actions: [
           'install the claworld plugin and write the managed config shape',
-          'activate the install through POST /v1/onboarding/activate',
-          'persist the returned appToken and verify the runtime binding',
+          'run claworld_pair_agent to confirm readiness after install',
+          'if public identity is pending, call claworld_update_public_identity',
+          'claworld_update_public_identity activates the backend binding when needed and persists the returned appToken',
           'collect required world profile fields',
           'validate world membership eligibility',
           'start the first A2A loop or deliver world content',

package/src/product-shell/profile/public-identity-routes.js

@@ -0,0 +1,60 @@
+import { resolveAuthenticatedAgentId } from '../../lib/http-auth.js';
+
+function sendProfileError(res, error) {
+  const status = Number.isInteger(error?.status) ? error.status : 500;
+  if (error?.responseBody && typeof error.responseBody === 'object') {
+    return res.status(status).json(error.responseBody);
+  }
+  const code = typeof error?.code === 'string' ? error.code : 'internal_error';
+  return res.status(status).json({ error: code, message: error?.message || code });
+}
+
+function sendMissingAgentIdentity(res) {
+  return res.status(401).json({
+    error: 'not_authenticated',
+    reason: 'agent_identity_required',
+  });
+}
+
+export function registerPublicIdentityRoutes(app, { publicIdentityService, store }) {
+  app.get('/v1/profile/public-identity', (req, res) => {
+    const authAgent = resolveAuthenticatedAgentId({
+      store,
+      req,
+      providedAgentId: req.query.agentId,
+      fieldName: 'agentId',
+    });
+    if (!authAgent.ok) return res.status(authAgent.status).json(authAgent.body);
+    if (!authAgent.agentId) return sendMissingAgentIdentity(res);
+
+    try {
+      const result = publicIdentityService.getPublicIdentityStatus({
+        agentId: authAgent.agentId,
+      });
+      return res.json(result);
+    } catch (error) {
+      return sendProfileError(res, error);
+    }
+  });
+
+  app.put('/v1/profile/public-identity', async (req, res) => {
+    const authAgent = resolveAuthenticatedAgentId({
+      store,
+      req,
+      providedAgentId: req.body?.agentId,
+      fieldName: 'agentId',
+    });
+    if (!authAgent.ok) return res.status(authAgent.status).json(authAgent.body);
+    if (!authAgent.agentId) return sendMissingAgentIdentity(res);
+
+    try {
+      const result = await publicIdentityService.updatePublicIdentity({
+        agentId: authAgent.agentId,
+        displayName: req.body?.displayName,
+      });
+      return res.json(result);
+    } catch (error) {
+      return sendProfileError(res, error);
+    }
+  });
+}

package/src/product-shell/profile/public-identity-service.js

@@ -0,0 +1,190 @@
+import {
+  buildPublicIdentityMissingFields,
+  formatPublicIdentityDisplay,
+  generatePublicIdentityCode,
+  PUBLIC_IDENTITY_STATUS,
+  resolvePublicIdentity,
+  validatePublicDisplayName,
+} from '../../lib/public-identity.js';
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function createConfigurationError() {
+  const error = new Error('public_identity_store_unavailable');
+  error.code = 'public_identity_store_unavailable';
+  error.status = 500;
+  return error;
+}
+
+function createAgentNotFoundError(agentId) {
+  const error = new Error(`agent_not_found:${agentId}`);
+  error.code = 'agent_not_found';
+  error.status = 404;
+  error.responseBody = {
+    error: error.code,
+    message: 'agent not found',
+    agentId: normalizeText(agentId, null),
+  };
+  return error;
+}
+
+function createInvalidPublicIdentityRequest(fieldId, message, code = 'invalid_public_identity') {
+  const error = new Error(code);
+  error.code = code;
+  error.status = 400;
+  error.responseBody = {
+    error: code,
+    message: 'public identity request is invalid',
+    fieldErrors: [
+      {
+        fieldId,
+        message,
+      },
+    ],
+  };
+  return error;
+}
+
+function createPublicIdentityIncompleteError(agent, {
+  capability = null,
+  nextTool = 'claworld_update_public_identity',
+} = {}) {
+  const projected = projectPublicIdentityStatus(agent, { nextTool });
+  const capabilityLabel = normalizeText(capability, 'this Claworld capability');
+  const error = new Error(`public_identity_incomplete:${agent?.agentId || 'unknown'}`);
+  error.code = 'public_identity_incomplete';
+  error.status = 409;
+  error.responseBody = {
+    status: 'blocked',
+    error: error.code,
+    message: `${capabilityLabel} requires a public Claworld identity`,
+    agentId: normalizeText(agent?.agentId, null),
+    requiredAction: projected.requiredAction,
+    nextAction: projected.nextAction,
+    nextTool: projected.nextTool,
+    missingFields: projected.missingFields,
+    publicIdentity: projected.publicIdentity,
+  };
+  return error;
+}
+
+function projectPublicIdentityStatus(agent, {
+  nextTool = 'claworld_update_public_identity',
+  conversationFeedbackService = null,
+} = {}) {
+  const publicIdentity = resolvePublicIdentity(agent);
+  const ready = publicIdentity.status === PUBLIC_IDENTITY_STATUS.READY;
+  return {
+    status: ready ? 'ready' : 'pending',
+    agentId: normalizeText(agent?.agentId, null),
+    ready,
+    publicIdentity: {
+      status: publicIdentity.status,
+      displayName: publicIdentity.displayName,
+      code: publicIdentity.code,
+      displayIdentity: formatPublicIdentityDisplay(publicIdentity),
+      confirmedAt: publicIdentity.confirmedAt,
+      updatedAt: publicIdentity.updatedAt,
+    },
+    recommendedDisplayName: normalizeText(agent?.displayName, publicIdentity.displayName || null),
+    nextAction: ready ? 'continue_claworld_flow' : 'set_public_identity',
+    requiredAction: ready ? null : 'set_public_identity',
+    nextTool: ready ? null : nextTool,
+    missingFields: ready ? [] : buildPublicIdentityMissingFields(agent),
+    feedbackSummary: conversationFeedbackService?.summarizeAgent?.({ agentId: agent?.agentId }) || {
+      totalLikesReceived: 0,
+      totalDislikesReceived: 0,
+      totalLikesGiven: 0,
+      totalDislikesGiven: 0,
+    },
+  };
+}
+
+export function createPublicIdentityService({ store = null, conversationFeedbackService = null } = {}) {
+  function assertStore() {
+    if (!store) throw createConfigurationError();
+    return store;
+  }
+
+  function requireAgent(agentId) {
+    const normalizedAgentId = normalizeText(agentId, null);
+    if (!normalizedAgentId) {
+      throw createInvalidPublicIdentityRequest('agentId', 'agentId is required');
+    }
+    const agent = assertStore().getAgent(normalizedAgentId);
+    if (!agent) throw createAgentNotFoundError(normalizedAgentId);
+    return agent;
+  }
+
+  function codeExists(code, excludeAgentId = null) {
+    return assertStore()
+      .listAgents()
+      .some((agent) => agent.agentId !== excludeAgentId && resolvePublicIdentity(agent).code === code);
+  }
+
+  function issueStableCode(agentId) {
+    for (let attempt = 0; attempt < 32; attempt += 1) {
+      const code = generatePublicIdentityCode();
+      if (!codeExists(code, agentId)) return code;
+    }
+    throw new Error('public_identity_code_generation_failed');
+  }
+
+  function isPublicIdentityCodeConflict(error) {
+    return error?.code === 'public_identity_code_conflict';
+  }
+
+  return {
+    getPublicIdentityStatus({ agentId } = {}) {
+      const agent = requireAgent(agentId);
+      return projectPublicIdentityStatus(agent, { conversationFeedbackService });
+    },
+
+    async updatePublicIdentity({ agentId, displayName } = {}) {
+      const agent = requireAgent(agentId);
+      const validation = validatePublicDisplayName(displayName);
+      if (!validation.ok) {
+        throw createInvalidPublicIdentityRequest('displayName', validation.message, validation.code);
+      }
+      const existingIdentity = resolvePublicIdentity(agent);
+      const stableCode = existingIdentity.code || null;
+
+      for (let attempt = 0; attempt < 32; attempt += 1) {
+        const now = assertStore().now();
+        const nextCode = stableCode || issueStableCode(agent.agentId);
+        try {
+          const updatedAgent = await assertStore().updateAgent(agent.agentId, {
+            displayName: validation.value,
+            publicIdentity: {
+              displayName: validation.value,
+              code: nextCode,
+              status: PUBLIC_IDENTITY_STATUS.READY,
+              confirmedAt: existingIdentity.confirmedAt || now,
+              updatedAt: now,
+            },
+          });
+          return projectPublicIdentityStatus(updatedAgent, { conversationFeedbackService });
+        } catch (error) {
+          if (!stableCode && isPublicIdentityCodeConflict(error)) {
+            continue;
+          }
+          throw error;
+        }
+      }
+
+      throw new Error('public_identity_code_generation_failed');
+    },
+
+    assertPublicIdentityReady({ agentId, capability = null } = {}) {
+      const agent = requireAgent(agentId);
+      if (resolvePublicIdentity(agent).status !== PUBLIC_IDENTITY_STATUS.READY) {
+        throw createPublicIdentityIncompleteError(agent, { capability });
+      }
+      return projectPublicIdentityStatus(agent, { conversationFeedbackService });
+    },
+  };
+}

package/src/product-shell/search/search-service.js

@@ -255,6 +255,7 @@ export function createWorldSearchService({
   worldAuthorizationService,
   store = null,
   presence = null,
+  conversationFeedbackService = null,
 } = {}) {
   function assertStore() {
     if (!store) throw createConfigurationError();
@@ -339,9 +340,8 @@ export function createWorldSearchService({
             playerId: candidateAgent.agentId,
             membershipId: membership.membershipId,
             worldId: world.worldId,
-            displayName: normalizeText(candidateAgent.displayName, candidateAgent.agentCode),
+            displayName: normalizeText(candidateAgent.displayName, candidateAgent.agentId),
             headline: normalizeText(membership.profileSnapshot?.headline, null),
-            address: candidateAgent.address,
             online: presenceState.online === true,
             connectedAt: presenceState.connectedAt,
             lastHeartbeatAt: presenceState.lastHeartbeatAt,
@@ -352,6 +352,13 @@ export function createWorldSearchService({
             reasonSummary: summarizeMatchedFields(matchedFields),
             joinedAt: membership.joinedAt,
             profileSummary: projectProfileSummary(world, membership.profileSnapshot || {}, candidateAgent),
+            worldFeedbackSummary: conversationFeedbackService?.summarizeWorldAgent?.({
+              worldId: world.worldId,
+              agentId: candidateAgent.agentId,
+            }) || {
+              likesReceived: 0,
+              dislikesReceived: 0,
+            },
           };
         })
         .filter(Boolean);

package/src/product-shell/social/chat-request-service.js

@@ -1,5 +1,6 @@
 import { normalizeAgentProfile, resolveAgentDisplayName, resolveAgentVisibility } from '../../lib/agent-profile.js';
 import { normalizeChatRequestInput } from '../../lib/chat-request.js';
+import { resolvePublicIdentity } from '../../lib/public-identity.js';
 import { createKickoffBrief, resolveStoredKickoffBrief } from '../../lib/relay/kickoff-text.js';
 import { WORLD_ACTIONS } from '../worlds/world-authorization.js';
 import { normalizeChatRequestApprovalPolicy } from '../contracts/chat-request-approval-policy.js';
@@ -67,7 +68,7 @@ function createAgentNotFoundError(agentId) {
   return error;
 }
 
-function createTargetAddressNotFoundError(targetAgentId) {
+function createTargetAgentNotFoundError(targetAgentId) {
   const error = new Error(`chat_request_target_not_found:${targetAgentId}`);
   error.code = 'chat_request_target_not_found';
   error.status = 404;
@@ -124,10 +125,8 @@ function projectAgent(store, agentId, presence = null) {
   const presenceState = presence?.getPresence?.(agent.agentId) || store.getPresence(agent.agentId);
   return {
     agentId: agent.agentId,
-    agentCode: agent.agentCode,
-    domain: agent.domain,
-    address: agent.address,
     displayName: resolveAgentDisplayName(agent),
+    publicIdentity: resolvePublicIdentity(agent),
     profile: normalizeAgentProfile(agent.profile),
     discoverable: visibility.discoverable,
     contactable: visibility.contactable,
@@ -374,6 +373,8 @@ export function createChatRequestService({
   presence = null,
   worldService = null,
   worldAuthorizationService = null,
+  publicIdentityService = null,
+  conversationFeedbackService = null,
 } = {}) {
   function assertStore() {
     if (!store) throw createConfigurationError('chat_request_store_unavailable');
@@ -440,6 +441,15 @@ export function createChatRequestService({
   function projectChatInboxChat(conversation = {}, viewerAgentId = null, request = null) {
     const direction = resolveInboxChatDirection(viewerAgentId, request);
     const counterpartyAgentId = resolveInboxChatCounterpartyAgentId(viewerAgentId, request, conversation);
+    const feedbackSummary = conversationFeedbackService?.summarizeConversation?.({
+      conversationKey: conversation.conversationKey,
+      viewerAgentId,
+    }) || {
+      likeCount: 0,
+      dislikeCount: 0,
+      viewerGave: null,
+      viewerReceived: null,
+    };
 
     return {
       chatRequestId: normalizeText(request?.chatRequestId || request?.requestId, null),
@@ -452,6 +462,7 @@ export function createChatRequestService({
       localSessionKey: normalizeText(conversation.sessionKey, null),
       counterparty: projectAgent(assertStore(), counterpartyAgentId, presence),
       conversation: resolveInboxConversationWorldSummary(worldService, request, conversation),
+      feedbackSummary,
     };
   }
 
@@ -501,6 +512,10 @@ export function createChatRequestService({
       source = 'chat_request',
     } = {}) {
       requireAgent(fromAgentId);
+      publicIdentityService?.assertPublicIdentityReady?.({
+        agentId: fromAgentId,
+        capability: 'request chat',
+      });
       const normalizedTargetAgentId = normalizeText(targetAgentId, null);
       if (!normalizedTargetAgentId) {
         throw createInvalidChatRequestError('chat_request_target_required', 'chat request target requires targetAgentId');
@@ -513,8 +528,8 @@ export function createChatRequestService({
       });
       const normalizedWorldId = normalizeConversationWorldId(worldId)
         || normalizeConversationWorldId(normalizedRequestInput.conversation?.worldId);
-      if (!targetAgent?.address) {
-        throw createTargetAddressNotFoundError(normalizedTargetAgentId);
+      if (!targetAgent?.agentId) {
+        throw createTargetAgentNotFoundError(normalizedTargetAgentId);
       }
       const normalizedOpeningPayload = cloneJsonObject(openingPayload) || cloneJsonObject(normalizedRequestInput.openingPayload);
       const normalizedKickoffBrief = createKickoffBrief({
@@ -549,7 +564,7 @@ export function createChatRequestService({
 
       const result = await assertRelay('createChatRequest').createChatRequest({
         fromAgentId,
-        toAddress: targetAgent.address,
+        targetAgentId: targetAgent.agentId,
         kickoffBrief: normalizedKickoffBrief,
         openingMessage: normalizeText(
           normalizedKickoffBrief?.text,

package/src/product-shell/social/friend-routes.js

@@ -12,7 +12,7 @@ export function registerFriendRoutes(app, { friendService }) {
     try {
       const result = await friendService.createFriendRequest({
         fromAgentId: req.body?.fromAgentId,
-        toAddress: req.body?.toAddress,
+        targetAgentId: req.body?.targetAgentId,
         message: req.body?.message,
         metadata: req.body?.metadata,
       });

package/src/product-shell/social/friend-service.js

@@ -1,16 +1,12 @@
 import { normalizeAgentProfile, resolveAgentDisplayName, resolveAgentVisibility } from '../../lib/agent-profile.js';
 import { createRelayPolicyHooks, evaluatePolicyHook } from '../../lib/policy.js';
+import { resolvePublicIdentity } from '../../lib/public-identity.js';
 
 function normalizeAgentId(agentId) {
   const normalized = String(agentId || '').trim();
   return normalized || null;
 }
 
-function normalizeAddress(address) {
-  const normalized = String(address || '').trim().toLowerCase();
-  return normalized || null;
-}
-
 function normalizeDirection(direction) {
   const normalized = String(direction || '').trim().toLowerCase();
   return normalized === 'inbound' || normalized === 'outbound' ? normalized : null;
@@ -54,8 +50,8 @@ function createAgentNotFoundError(agentId) {
   return error;
 }
 
-function createTargetNotFoundError(address) {
-  const error = new Error(`friend_target_not_found:${address}`);
+function createTargetNotFoundError(targetAgentId) {
+  const error = new Error(`friend_target_not_found:${targetAgentId}`);
   error.code = 'friend_target_not_found';
   error.status = 404;
   return error;
@@ -131,10 +127,8 @@ function projectAgent(store, agentId) {
   const visibility = resolveAgentVisibility(agent);
   return {
     agentId: agent.agentId,
-    agentCode: agent.agentCode,
-    domain: agent.domain,
-    address: agent.address,
     displayName: resolveAgentDisplayName(agent),
+    publicIdentity: resolvePublicIdentity(agent),
     profile: normalizeAgentProfile(agent.profile),
     discoverable: visibility.discoverable,
     contactable: visibility.contactable,
@@ -149,7 +143,7 @@ function resolvePeerAgentId(friendship, viewerAgentId) {
   return null;
 }
 
-export function createFriendService({ store = null, policy = null } = {}) {
+export function createFriendService({ store = null, policy = null, publicIdentityService = null } = {}) {
   const relayPolicy = createRelayPolicyHooks(policy);
 
   function assertStore() {
@@ -307,23 +301,27 @@ export function createFriendService({ store = null, policy = null } = {}) {
   }
 
   return {
-    async createFriendRequest({ fromAgentId, toAddress, message = null, metadata = {} } = {}) {
+    async createFriendRequest({ fromAgentId, targetAgentId, message = null, metadata = {} } = {}) {
       const friendshipStore = assertStore();
       const fromAgent = requireAgent(fromAgentId);
-      const normalizedToAddress = normalizeAddress(toAddress);
-      if (!normalizedToAddress) {
-        throw createTargetNotFoundError(toAddress);
+      publicIdentityService?.assertPublicIdentityReady?.({
+        agentId: fromAgent.agentId,
+        capability: 'send friend request',
+      });
+      const normalizedTargetAgentId = normalizeAgentId(targetAgentId);
+      if (!normalizedTargetAgentId) {
+        throw createTargetNotFoundError(targetAgentId);
       }
 
-      const toAgent = friendshipStore.resolveAddress(normalizedToAddress);
-      if (!toAgent) throw createTargetNotFoundError(normalizedToAddress);
+      const toAgent = friendshipStore.getAgent(normalizedTargetAgentId);
+      if (!toAgent) throw createTargetNotFoundError(normalizedTargetAgentId);
 
       const canRequest = evaluatePolicyHook({
         hook: relayPolicy.canRequest,
         context: {
           fromAgentId: fromAgent.agentId,
           fromAgent,
-          toAddress: normalizedToAddress,
+          targetAgentId: normalizedTargetAgentId,
           toAgent,
           requestContext: {
             type: 'friend_request',
@@ -382,7 +380,6 @@ export function createFriendService({ store = null, policy = null } = {}) {
       const request = await friendshipStore.createFriendRequest({
         fromAgentId: fromAgent.agentId,
         toAgentId: toAgent.agentId,
-        toAddress: toAgent.address,
         message: normalizeMessage(message),
         metadata,
       });

package/src/product-shell/social/social-routes.js

@@ -10,8 +10,8 @@ function sendSocialError(res, error) {
 export function registerSocialRoutes(app, { socialService }) {
   app.get('/v1/social/agents/lookup', (req, res) => {
     try {
-      const result = socialService.lookupAgentByCode({
-        agentCode: req.query.agentCode,
+      const result = socialService.lookupAgentByIdentity({
+        identity: req.query.identity,
       });
       res.json(result);
     } catch (error) {