@xfxstudio/claworld 0.2.9 → 0.2.10-beta.0

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) {

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

@@ -3,7 +3,7 @@ import {
   resolveAgentDisplayName,
   resolveAgentVisibility,
 } from '../../lib/agent-profile.js';
-import { parseAgentHandle } from '../../lib/agent-address.js';
+import { parsePublicIdentityDisplay, resolvePublicIdentity } from '../../lib/public-identity.js';
 
 function normalizeText(value, fallback = null) {
   if (value == null) return fallback;
@@ -11,18 +11,6 @@ function normalizeText(value, fallback = null) {
   return normalized || fallback;
 }
 
-function parseCanonicalAgentCode(value) {
-  const parsed = parseAgentHandle(value);
-  if (!parsed?.canonical) return null;
-
-  return {
-    agentCode: parsed.address,
-    relayLocalCode: parsed.localPart,
-    domain: parsed.domain,
-    address: parsed.address,
-  };
-}
-
 function createConfigurationError() {
   const error = new Error('social_lookup_store_unavailable');
   error.code = 'social_lookup_store_unavailable';
@@ -30,44 +18,44 @@ function createConfigurationError() {
   return error;
 }
 
-function createInvalidAgentCodeError(agentCode) {
-  const error = new Error('invalid_agent_code');
-  error.code = 'invalid_agent_code';
+function createInvalidPublicIdentityError(identity) {
+  const error = new Error('invalid_public_identity');
+  error.code = 'invalid_public_identity';
   error.status = 400;
   error.responseBody = {
     error: error.code,
-    message: 'agentCode must use canonical local@namespace schema',
-    agentCode: normalizeText(agentCode, null),
+    message: 'identity must use displayName#code',
+    identity: normalizeText(identity, null),
     fieldErrors: [
       {
-        fieldId: 'agentCode',
-        message: 'agentCode must use canonical local@namespace schema',
+        fieldId: 'identity',
+        message: 'identity must use displayName#code',
       },
     ],
   };
   return error;
 }
 
-function createAgentNotFoundError(agentCode) {
-  const error = new Error(`agent_not_found:${agentCode}`);
+function createAgentNotFoundError(identity) {
+  const error = new Error(`agent_not_found:${identity}`);
   error.code = 'agent_not_found';
   error.status = 404;
   error.responseBody = {
     error: error.code,
-    message: 'no agent found for canonical agentCode',
-    agentCode,
+    message: 'no agent found for public identity',
+    identity,
   };
   return error;
 }
 
-function createNotDiscoverableError(agentCode) {
-  const error = new Error(`not_discoverable:${agentCode}`);
+function createNotDiscoverableError(identity) {
+  const error = new Error(`not_discoverable:${identity}`);
   error.code = 'not_discoverable';
   error.status = 403;
   error.responseBody = {
     error: error.code,
     message: 'agent is not discoverable',
-    agentCode,
+    identity,
   };
   return error;
 }
@@ -94,21 +82,27 @@ export function createSocialService({ worldService, store = null } = {}) {
   }
 
   return {
-    lookupAgentByCode({ agentCode } = {}) {
+    lookupAgentByIdentity({ identity } = {}) {
       const socialStore = assertStore();
-      const parsedAgentCode = parseCanonicalAgentCode(agentCode);
-      if (!parsedAgentCode) {
-        throw createInvalidAgentCodeError(agentCode);
+      const parsedIdentity = parsePublicIdentityDisplay(identity);
+      if (!parsedIdentity) {
+        throw createInvalidPublicIdentityError(identity);
       }
 
-      const agent = socialStore.resolveAddress(parsedAgentCode.address);
+      const agent = socialStore
+        .listAgents()
+        .find((candidate) => {
+          const candidateIdentity = resolvePublicIdentity(candidate);
+          return candidateIdentity.status === 'ready'
+            && candidateIdentity.code === parsedIdentity.code;
+        }) || null;
       if (!agent) {
-        throw createAgentNotFoundError(parsedAgentCode.agentCode);
+        throw createAgentNotFoundError(parsedIdentity.identity);
       }
 
       const visibility = resolveAgentVisibility(agent);
       if (!visibility.discoverable) {
-        throw createNotDiscoverableError(parsedAgentCode.agentCode);
+        throw createNotDiscoverableError(parsedIdentity.identity);
       }
 
       const activeWorlds = socialStore
@@ -124,8 +118,10 @@ export function createSocialService({ worldService, store = null } = {}) {
       return {
         status: 'found',
         publicProfile: {
-          agentCode: agent.address || parsedAgentCode.agentCode,
+          agentId: agent.agentId,
+          identity: resolvePublicIdentity(agent).displayIdentity || parsedIdentity.identity,
           displayName: resolveAgentDisplayName(agent),
+          code: resolvePublicIdentity(agent).code,
           profile: normalizeAgentProfile(agent.profile),
           discoverable: visibility.discoverable,
           contactable: visibility.contactable,