@xfxstudio/claworld 0.2.9 → 0.2.10-beta.0

package/src/product-shell/conversation-feedback/conversation-feedback-service.js

@@ -0,0 +1,261 @@
+const FEEDBACK_TOKEN_TO_SENTIMENT = Object.freeze({
+  '[[like]]': 'like',
+  '[[dislike]]': 'dislike',
+});
+
+const SENTIMENT_VALUES = Object.freeze(['like', 'dislike']);
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function createConfigurationError() {
+  const error = new Error('conversation_feedback_store_unavailable');
+  error.code = 'conversation_feedback_store_unavailable';
+  error.status = 500;
+  return error;
+}
+
+function createInvalidConversationFeedbackError(fieldId, message = `${fieldId} is required`) {
+  const error = new Error(`invalid_conversation_feedback:${fieldId}`);
+  error.code = 'invalid_conversation_feedback';
+  error.status = 400;
+  error.responseBody = {
+    error: error.code,
+    message: 'conversation feedback request is invalid',
+    fieldErrors: [
+      {
+        fieldId,
+        message,
+      },
+    ],
+  };
+  return error;
+}
+
+function normalizeSentiment(value, fallback = null) {
+  const normalized = normalizeText(value, fallback);
+  return SENTIMENT_VALUES.includes(normalized) ? normalized : fallback;
+}
+
+function resolveSentimentFromToken(token = null) {
+  const normalizedToken = normalizeText(token, null);
+  return normalizedToken ? FEEDBACK_TOKEN_TO_SENTIMENT[normalizedToken] || null : null;
+}
+
+export function parseConversationFeedbackTokens(text = '') {
+  if (typeof text !== 'string' || !text.trim()) {
+    return {
+      tokens: [],
+      sentiment: null,
+      conflict: false,
+    };
+  }
+
+  const matches = [...text.matchAll(/\[\[(like|dislike)\]\]/g)];
+  if (matches.length === 0) {
+    return {
+      tokens: [],
+      sentiment: null,
+      conflict: false,
+    };
+  }
+
+  const tokens = [...new Set(matches.map((match) => `[[${String(match[1] || '').trim().toLowerCase()}]]`))];
+  const sentiments = [...new Set(tokens.map((token) => resolveSentimentFromToken(token)).filter(Boolean))];
+  return {
+    tokens,
+    sentiment: sentiments.length === 1 ? sentiments[0] : null,
+    conflict: sentiments.length > 1,
+  };
+}
+
+function projectFeedbackMark(feedbackMark = {}) {
+  return {
+    feedbackMarkId: normalizeText(feedbackMark.feedbackMarkId, null),
+    conversationKey: normalizeText(feedbackMark.conversationKey, null),
+    worldId: normalizeText(feedbackMark.worldId, null),
+    giverAgentId: normalizeText(feedbackMark.giverAgentId, null),
+    receiverAgentId: normalizeText(feedbackMark.receiverAgentId, null),
+    sourceTurnId: normalizeText(feedbackMark.sourceTurnId, null),
+    sourceDeliveryId: normalizeText(feedbackMark.sourceDeliveryId, null),
+    token: normalizeText(feedbackMark.token, null),
+    sentiment: normalizeSentiment(feedbackMark.sentiment, null),
+    source: normalizeText(feedbackMark.source, 'reply_control_token'),
+    status: normalizeText(feedbackMark.status, 'active'),
+    createdAt: normalizeText(feedbackMark.createdAt, null),
+    updatedAt: normalizeText(feedbackMark.updatedAt, normalizeText(feedbackMark.createdAt, null)),
+  };
+}
+
+function summarizeReceived(items = []) {
+  return {
+    likesReceived: items.filter((item) => item.sentiment === 'like').length,
+    dislikesReceived: items.filter((item) => item.sentiment === 'dislike').length,
+  };
+}
+
+export function createConversationFeedbackService({ store } = {}) {
+  if (
+    !store
+    || typeof store.createConversationFeedbackMark !== 'function'
+    || typeof store.listConversationFeedbackMarks !== 'function'
+    || typeof store.findConversationFeedbackMarkByConversationAndActors !== 'function'
+  ) {
+    throw createConfigurationError();
+  }
+
+  return {
+    parseTokens(text = '') {
+      return parseConversationFeedbackTokens(text);
+    },
+
+    async recordFeedback({
+      conversationKey,
+      worldId = null,
+      giverAgentId,
+      receiverAgentId,
+      sourceTurnId = null,
+      sourceDeliveryId = null,
+      token = null,
+      sentiment = null,
+    } = {}) {
+      const normalizedConversationKey = normalizeText(conversationKey, null);
+      if (!normalizedConversationKey) {
+        throw createInvalidConversationFeedbackError('conversationKey');
+      }
+      const normalizedGiverAgentId = normalizeText(giverAgentId, null);
+      if (!normalizedGiverAgentId) {
+        throw createInvalidConversationFeedbackError('giverAgentId');
+      }
+      const normalizedReceiverAgentId = normalizeText(receiverAgentId, null);
+      if (!normalizedReceiverAgentId) {
+        throw createInvalidConversationFeedbackError('receiverAgentId');
+      }
+      const normalizedToken = normalizeText(token, null);
+      const normalizedSentiment = normalizeSentiment(sentiment, resolveSentimentFromToken(normalizedToken));
+      if (!normalizedSentiment) {
+        throw createInvalidConversationFeedbackError('sentiment', 'sentiment must be like or dislike');
+      }
+
+      const existing = store.findConversationFeedbackMarkByConversationAndActors({
+        conversationKey: normalizedConversationKey,
+        giverAgentId: normalizedGiverAgentId,
+        receiverAgentId: normalizedReceiverAgentId,
+      });
+      if (existing) {
+        return {
+          recorded: false,
+          deduped: true,
+          feedbackMark: projectFeedbackMark(existing),
+        };
+      }
+
+      const feedbackMark = await store.createConversationFeedbackMark({
+        conversationKey: normalizedConversationKey,
+        worldId: normalizeText(worldId, null),
+        giverAgentId: normalizedGiverAgentId,
+        receiverAgentId: normalizedReceiverAgentId,
+        sourceTurnId: normalizeText(sourceTurnId, null),
+        sourceDeliveryId: normalizeText(sourceDeliveryId, null),
+        token: normalizedToken || `[[${normalizedSentiment}]]`,
+        sentiment: normalizedSentiment,
+        source: 'reply_control_token',
+        status: 'active',
+      });
+
+      return {
+        recorded: true,
+        deduped: false,
+        feedbackMark: projectFeedbackMark(feedbackMark),
+      };
+    },
+
+    listFeedbackMarks(filters = {}) {
+      return store.listConversationFeedbackMarks(filters).map((item) => projectFeedbackMark(item));
+    },
+
+    summarizeConversation({ conversationKey, viewerAgentId = null } = {}) {
+      const normalizedConversationKey = normalizeText(conversationKey, null);
+      const normalizedViewerAgentId = normalizeText(viewerAgentId, null);
+      const items = normalizedConversationKey
+        ? this.listFeedbackMarks({ conversationKey: normalizedConversationKey, status: 'active' })
+        : [];
+      const viewerGave = normalizedViewerAgentId
+        ? items.find((item) => item.giverAgentId === normalizedViewerAgentId)?.sentiment || null
+        : null;
+      const viewerReceived = normalizedViewerAgentId
+        ? items.find((item) => item.receiverAgentId === normalizedViewerAgentId)?.sentiment || null
+        : null;
+      return {
+        likeCount: items.filter((item) => item.sentiment === 'like').length,
+        dislikeCount: items.filter((item) => item.sentiment === 'dislike').length,
+        viewerGave,
+        viewerReceived,
+      };
+    },
+
+    summarizeAgent({ agentId } = {}) {
+      const normalizedAgentId = normalizeText(agentId, null);
+      if (!normalizedAgentId) {
+        return {
+          totalLikesReceived: 0,
+          totalDislikesReceived: 0,
+          totalLikesGiven: 0,
+          totalDislikesGiven: 0,
+        };
+      }
+      const received = this.listFeedbackMarks({
+        receiverAgentId: normalizedAgentId,
+        status: 'active',
+      });
+      const given = this.listFeedbackMarks({
+        giverAgentId: normalizedAgentId,
+        status: 'active',
+      });
+
+      return {
+        totalLikesReceived: received.filter((item) => item.sentiment === 'like').length,
+        totalDislikesReceived: received.filter((item) => item.sentiment === 'dislike').length,
+        totalLikesGiven: given.filter((item) => item.sentiment === 'like').length,
+        totalDislikesGiven: given.filter((item) => item.sentiment === 'dislike').length,
+      };
+    },
+
+    summarizeWorldAgent({ worldId, agentId } = {}) {
+      const normalizedWorldId = normalizeText(worldId, null);
+      const normalizedAgentId = normalizeText(agentId, null);
+      if (!normalizedWorldId || !normalizedAgentId) {
+        return {
+          likesReceived: 0,
+          dislikesReceived: 0,
+        };
+      }
+      return summarizeReceived(this.listFeedbackMarks({
+        worldId: normalizedWorldId,
+        receiverAgentId: normalizedAgentId,
+        status: 'active',
+      }));
+    },
+
+    summarizeWorld({ worldId } = {}) {
+      const normalizedWorldId = normalizeText(worldId, null);
+      if (!normalizedWorldId) {
+        return {
+          totalLikes: 0,
+          totalDislikes: 0,
+        };
+      }
+      const items = this.listFeedbackMarks({
+        worldId: normalizedWorldId,
+        status: 'active',
+      });
+      return {
+        totalLikes: items.filter((item) => item.sentiment === 'like').length,
+        totalDislikes: items.filter((item) => item.sentiment === 'dislike').length,
+      };
+    },
+  };
+}

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

@@ -57,7 +57,6 @@ export function registerFeedbackRoutes(app, { store, feedbackService }) {
         turnId: req.body?.turnId,
         deliveryId: req.body?.deliveryId,
         targetAgentId: req.body?.targetAgentId,
-        targetAgentCode: req.body?.targetAgentCode,
         tags: req.body?.tags,
         metadata: req.body?.metadata,
         context: req.body?.context,

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

@@ -2,6 +2,7 @@ import {
   FEEDBACK_CATEGORY_VALUES,
   FEEDBACK_IMPACT_VALUES,
 } from './feedback-contract.js';
+import { resolvePublicIdentity } from '../../lib/public-identity.js';
 
 function normalizeText(value, fallback = null) {
   if (value == null) return fallback;
@@ -111,13 +112,11 @@ function projectFeedback(feedback = {}) {
     reporter: feedback.reporter && typeof feedback.reporter === 'object'
       ? {
           agentId: feedback.reporter.agentId || null,
-          agentCode: feedback.reporter.agentCode || null,
-          address: feedback.reporter.address || null,
+          publicIdentity: feedback.reporter.publicIdentity || null,
         }
       : {
           agentId: null,
-          agentCode: null,
-          address: null,
+          publicIdentity: null,
         },
     context: feedback.context && typeof feedback.context === 'object'
       ? {
@@ -126,7 +125,6 @@ function projectFeedback(feedback = {}) {
           turnId: feedback.context.turnId || null,
           deliveryId: feedback.context.deliveryId || null,
           targetAgentId: feedback.context.targetAgentId || null,
-          targetAgentCode: feedback.context.targetAgentCode || null,
           tags: Array.isArray(feedback.context.tags) ? feedback.context.tags : [],
           metadata: feedback.context.metadata && typeof feedback.context.metadata === 'object'
             ? feedback.context.metadata
@@ -138,7 +136,6 @@ function projectFeedback(feedback = {}) {
           turnId: null,
           deliveryId: null,
           targetAgentId: null,
-          targetAgentCode: null,
           tags: [],
           metadata: {},
         },
@@ -178,8 +175,7 @@ export function createFeedbackService({ store } = {}) {
         accountId: normalizeText(input.accountId, null),
         reporter: {
           agentId: reporter.agentId,
-          agentCode: reporter.agentCode,
-          address: reporter.address,
+          publicIdentity: resolvePublicIdentity(reporter),
         },
         context: {
           worldId: normalizeText(input.worldId, normalizeText(context.worldId, null)),
@@ -187,7 +183,6 @@ export function createFeedbackService({ store } = {}) {
           turnId: normalizeText(input.turnId, normalizeText(context.turnId, null)),
           deliveryId: normalizeText(input.deliveryId, normalizeText(context.deliveryId, null)),
           targetAgentId: normalizeText(input.targetAgentId, normalizeText(context.targetAgentId, null)),
-          targetAgentCode: normalizeText(input.targetAgentCode, normalizeText(context.targetAgentCode, null)),
           tags: normalizeStringList(input.tags || context.tags),
           metadata: normalizePlainObject(input.metadata && Object.keys(input.metadata || {}).length > 0 ? input.metadata : context.metadata),
         },

package/src/product-shell/index.js

@@ -6,6 +6,8 @@ import { createWorldBroadcastService } from './worlds/world-broadcast-service.js
 import { DEFAULT_WORLD_MANIFESTS } from './catalog/default-world-catalog.js';
 import { createOnboardingService } from './onboarding/onboarding-service.js';
 import { registerOnboardingRoutes } from './onboarding/onboarding-routes.js';
+import { createPublicIdentityService } from './profile/public-identity-service.js';
+import { registerPublicIdentityRoutes } from './profile/public-identity-routes.js';
 import { createMembershipService } from './membership/membership-service.js';
 import { createMatchmakingService } from './matching/matchmaking-service.js';
 import { createWorldSearchService } from './search/search-service.js';
@@ -18,6 +20,7 @@ import { createChatRequestService } from './social/chat-request-service.js';
 import { registerChatRequestRoutes } from './social/chat-request-routes.js';
 import { createFeedbackService } from './feedback/feedback-service.js';
 import { registerFeedbackRoutes } from './feedback/feedback-routes.js';
+import { createConversationFeedbackService } from './conversation-feedback/conversation-feedback-service.js';
 
 export function createClaworldProductShell({
   worldCatalog = DEFAULT_WORLD_MANIFESTS,
@@ -27,20 +30,42 @@ export function createClaworldProductShell({
 } = {}) {
   const worldService = createWorldService({ worldCatalog, store });
   const onboardingService = createOnboardingService({ worldService, store });
-  const membershipService = createMembershipService({ worldService, store });
+  const publicIdentityService = createPublicIdentityService({ store });
+  const membershipService = createMembershipService({ worldService, store, publicIdentityService });
   const worldAuthorizationService = createWorldAuthorizationService({
     worldService,
     membershipService,
   });
-  const matchmakingService = createMatchmakingService({ worldService, worldAuthorizationService, store, presence });
-  const searchService = createWorldSearchService({ worldService, worldAuthorizationService, store, presence });
-  const worldAdminService = createWorldAdminService({ worldService, worldAuthorizationService, store });
+  const conversationFeedbackService = createConversationFeedbackService({ store });
+  const matchmakingService = createMatchmakingService({
+    worldService,
+    worldAuthorizationService,
+    store,
+    presence,
+    conversationFeedbackService,
+  });
+  const searchService = createWorldSearchService({
+    worldService,
+    worldAuthorizationService,
+    store,
+    presence,
+    conversationFeedbackService,
+  });
+  const worldAdminService = createWorldAdminService({
+    worldService,
+    worldAuthorizationService,
+    store,
+    publicIdentityService,
+    conversationFeedbackService,
+  });
   const chatRequestService = createChatRequestService({
     store,
     relay,
     presence,
     worldService,
     worldAuthorizationService,
+    publicIdentityService,
+    conversationFeedbackService,
   });
   const worldBroadcastService = createWorldBroadcastService({
     worldService,
@@ -49,13 +74,14 @@ export function createClaworldProductShell({
     chatRequestService,
     store,
   });
-  const friendService = createFriendService({ store, policy: relay?.policy });
+  const friendService = createFriendService({ store, policy: relay?.policy, publicIdentityService });
   const socialLookupService = createSocialService({ worldService, store });
   const feedbackService = createFeedbackService({ store });
+  const profileService = createPublicIdentityService({ store, conversationFeedbackService });
   const socialService = {
     ...friendService,
-    lookupAgentByCode(input) {
-      return socialLookupService.lookupAgentByCode(input);
+    lookupAgentByIdentity(input) {
+      return socialLookupService.lookupAgentByIdentity(input);
     },
   };
   const worldConversationOrchestrator = createWorldConversationOrchestrator({
@@ -65,6 +91,7 @@ export function createClaworldProductShell({
   const productShell = {
     contexts: {
       onboarding: onboardingService,
+      profile: profileService,
       worlds: worldService,
       worldAuthorization: worldAuthorizationService,
       membership: membershipService,
@@ -75,10 +102,12 @@ export function createClaworldProductShell({
       chatRequests: chatRequestService,
       moderation: worldAdminService,
       feedback: feedbackService,
+      conversationFeedback: conversationFeedbackService,
       orchestration: worldConversationOrchestrator,
     },
     registerRoutes(app) {
       registerOnboardingRoutes(app, { onboardingService, store });
+      registerPublicIdentityRoutes(app, { publicIdentityService: profileService, store });
       registerFriendRoutes(app, { friendService });
       registerChatRequestRoutes(app, { chatRequestService, store });
       registerWorldRoutes(app, {
@@ -101,6 +130,7 @@ export function createClaworldProductShell({
         compatibleWith: ['relay_backend', 'openclaw_channel_plugin'],
         boundedContexts: [
           'onboarding',
+          'profile',
           'worlds',
           'membership',
           'matchmaking',
@@ -110,6 +140,7 @@ export function createClaworldProductShell({
           'chatRequests',
           'moderation',
           'feedback',
+          'conversationFeedback',
           'orchestration',
         ],
         routes: [
@@ -117,6 +148,8 @@ export function createClaworldProductShell({
           'GET /v1/meta/install',
           'GET /v1/onboarding/plan',
           'POST /v1/onboarding/activate',
+          'GET /v1/profile/public-identity',
+          'PUT /v1/profile/public-identity',
           'POST /v1/friend-requests',
           'GET /v1/friend-requests',
           'POST /v1/friend-requests/:friendRequestId/accept',

package/src/product-shell/matching/matchmaking-service.js

@@ -263,6 +263,7 @@ function buildDatingDemoFeed({
   limit,
   worldAuthorizationService,
   resolvePresence,
+  conversationFeedbackService = null,
 }) {
   const { viewerMembership, activeMemberships, normalizedLimit, baseFeed } = buildBaseFeed({
     world,
@@ -278,6 +279,13 @@ function buildDatingDemoFeed({
       const candidateMembership = membershipById.get(candidate.sourceMembershipId);
       return {
         ...candidate,
+        worldFeedbackSummary: conversationFeedbackService?.summarizeWorldAgent?.({
+          worldId: world.worldId,
+          agentId: candidate.targetAgentId,
+        }) || {
+          likesReceived: 0,
+          dislikesReceived: 0,
+        },
         ...buildDatingDemoScoreDetails(viewerMembership, candidateMembership),
       };
     })
@@ -306,6 +314,7 @@ export function createMatchmakingService({
   worldAuthorizationService,
   store = null,
   presence = null,
+  conversationFeedbackService = null,
 } = {}) {
   function assertStore() {
     if (!store) throw createConfigurationError();
@@ -345,6 +354,7 @@ export function createMatchmakingService({
           limit,
           worldAuthorizationService,
           resolvePresence,
+          conversationFeedbackService,
         });
       }
 
@@ -364,7 +374,18 @@ export function createMatchmakingService({
         candidateSource: 'active_memberships_online',
         strategy: buildStrategy(world),
         totalCandidates: baseFeed.candidates.length,
-        candidates: baseFeed.candidates.slice(0, normalizedLimit),
+        candidates: baseFeed.candidates
+          .slice(0, normalizedLimit)
+          .map((candidate) => ({
+            ...candidate,
+            worldFeedbackSummary: conversationFeedbackService?.summarizeWorldAgent?.({
+              worldId: world.worldId,
+              agentId: candidate.targetAgentId,
+            }) || {
+              likesReceived: 0,
+              dislikesReceived: 0,
+            },
+          })),
       };
     },
     listCandidates(options = {}) {

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

@@ -65,7 +65,7 @@ function buildNextStageSummary() {
   };
 }
 
-export function createMembershipService({ worldService, store = null } = {}) {
+export function createMembershipService({ worldService, store = null, publicIdentityService = null } = {}) {
   function assertStore() {
     if (!store) throw createConfigurationError();
     return store;
@@ -193,6 +193,10 @@ export function createMembershipService({ worldService, store = null } = {}) {
 
       const agent = membershipStore.getAgent(normalizedAgentId);
       if (!agent) throw createAgentNotFoundError(normalizedAgentId);
+      publicIdentityService?.assertPublicIdentityReady?.({
+        agentId: normalizedAgentId,
+        capability: 'join world',
+      });
 
       const normalizedParticipantContextText = resolveNormalizedParticipantContextText({
         world,

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',

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);
+    }
+  });
+}