@xfxstudio/claworld 0.2.10-beta.3 → 0.2.12

package/src/product-shell/agent-cards/template-registry.js

@@ -0,0 +1,131 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const TEMPLATE_DEFINITIONS = Object.freeze([
+  {
+    templateId: 'agent-card.figma-v2',
+    templateVersion: 'v1',
+    width: 1077,
+    height: 1443,
+    templatePath: path.join(__dirname, 'templates', 'agent-card.figma-v2.svg'),
+    description: 'Embedded Figma-export card with centered name/handle over the illustrated shrimp poster.',
+  },
+  {
+    templateId: 'agent-card.slot-01',
+    templateVersion: 'v1',
+    width: 1792,
+    height: 2400,
+    templatePath: path.join(__dirname, 'templates', 'agent-card.slot-01.svg'),
+    description: 'Slot-driven poster card with wide centered name/handle fields and shrink-to-fit metadata.',
+  },
+  {
+    templateId: 'agent-card.slot-02',
+    templateVersion: 'v1',
+    width: 1792,
+    height: 2400,
+    templatePath: path.join(__dirname, 'templates', 'agent-card.slot-02.svg'),
+    description: 'Slot-driven right-side card with centered adaptive text fields and tighter width constraints.',
+  },
+  {
+    templateId: 'agent-card.slot-03',
+    templateVersion: 'v1',
+    width: 1792,
+    height: 2400,
+    templatePath: path.join(__dirname, 'templates', 'agent-card.slot-03.svg'),
+    description: 'Slot-driven wide centered card with larger adaptive text fields over an embedded background.',
+  },
+  {
+    templateId: 'agent-card.slot-04',
+    templateVersion: 'v1',
+    width: 1792,
+    height: 2400,
+    templatePath: path.join(__dirname, 'templates', 'agent-card.slot-04.svg'),
+    description: 'Slot-driven centered card with compact adaptive text fields over an embedded earthy background.',
+  },
+  {
+    templateId: 'agent-card.slot-05',
+    templateVersion: 'v1',
+    width: 1792,
+    height: 2400,
+    templatePath: path.join(__dirname, 'templates', 'agent-card.slot-05.svg'),
+    description: 'Figma-adjusted poster card with left-anchored adaptive name and handle slots.',
+  },
+  {
+    templateId: 'agent-card.slot-06',
+    templateVersion: 'v1',
+    width: 1792,
+    height: 2400,
+    templatePath: path.join(__dirname, 'templates', 'agent-card.slot-06.svg'),
+    description: 'Slot-driven right-column card with centered adaptive text fields over an embedded background.',
+  },
+  {
+    templateId: 'agent-card.slot-07',
+    templateVersion: 'v1',
+    width: 1792,
+    height: 2400,
+    templatePath: path.join(__dirname, 'templates', 'agent-card.slot-07.svg'),
+    description: 'Figma-adjusted warm poster card with large left-anchored adaptive name and handle slots.',
+  },
+  {
+    templateId: 'agent-card.slot-08',
+    templateVersion: 'v1',
+    width: 1792,
+    height: 2400,
+    templatePath: path.join(__dirname, 'templates', 'agent-card.slot-08.svg'),
+    description: 'Figma-adjusted rotated poster card with adaptive slanted name and handle slots.',
+  },
+]);
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+export function createAgentCardTemplateRegistry() {
+  const sourceCache = new Map();
+  const templatesById = new Map(TEMPLATE_DEFINITIONS.map((template) => [template.templateId, template]));
+
+  async function loadSource(template) {
+    const cached = sourceCache.get(template.templateId);
+    if (cached) return cached;
+    const source = await fs.readFile(template.templatePath, 'utf8');
+    sourceCache.set(template.templateId, source);
+    return source;
+  }
+
+  return {
+    listTemplates() {
+      return TEMPLATE_DEFINITIONS.map((template) => ({
+        templateId: template.templateId,
+        templateVersion: template.templateVersion,
+        width: template.width,
+        height: template.height,
+        description: template.description,
+      }));
+    },
+    async getTemplate(templateId = TEMPLATE_DEFINITIONS[0].templateId) {
+      const normalizedTemplateId = normalizeText(templateId, TEMPLATE_DEFINITIONS[0].templateId);
+      const template = templatesById.get(normalizedTemplateId) || null;
+      if (!template) {
+        const error = new Error(`unknown_agent_card_template:${normalizedTemplateId}`);
+        error.code = 'unknown_agent_card_template';
+        error.status = 404;
+        error.responseBody = {
+          error: error.code,
+          message: 'agent card template not found',
+          templateId: normalizedTemplateId,
+        };
+        throw error;
+      }
+
+      return {
+        ...template,
+        source: await loadSource(template),
+      };
+    },
+  };
+}

package/src/product-shell/index.js

@@ -7,6 +7,7 @@ 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 { createProfileService } from './profile/profile-service.js';
 import { registerPublicIdentityRoutes } from './profile/public-identity-routes.js';
 import { createMembershipService } from './membership/membership-service.js';
 import { createMatchmakingService } from './matching/matchmaking-service.js';
@@ -21,22 +22,25 @@ 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';
+import { createAgentCardService } from './agent-cards/card-service.js';
+import { registerAgentCardRoutes } from './agent-cards/card-routes.js';
 
 export function createClaworldProductShell({
   worldCatalog = DEFAULT_WORLD_MANIFESTS,
   relay = null,
   store = null,
   presence = null,
+  agentCard = {},
 } = {}) {
   const worldService = createWorldService({ worldCatalog, store });
+  const conversationFeedbackService = createConversationFeedbackService({ store });
   const onboardingService = createOnboardingService({ worldService, store });
-  const publicIdentityService = createPublicIdentityService({ store });
+  const publicIdentityService = createPublicIdentityService({ store, conversationFeedbackService });
   const membershipService = createMembershipService({ worldService, store, publicIdentityService });
   const worldAuthorizationService = createWorldAuthorizationService({
     worldService,
     membershipService,
   });
-  const conversationFeedbackService = createConversationFeedbackService({ store });
   const matchmakingService = createMatchmakingService({
     worldService,
     worldAuthorizationService,
@@ -77,7 +81,14 @@ export function createClaworldProductShell({
   const friendService = createFriendService({ store, policy: relay?.policy, publicIdentityService });
   const socialLookupService = createSocialService({ worldService, store });
   const feedbackService = createFeedbackService({ store });
-  const profileService = createPublicIdentityService({ store, conversationFeedbackService });
+  const agentCardService = createAgentCardService({
+    store,
+    ...agentCard,
+  });
+  const profileService = createProfileService({
+    publicIdentityService,
+    agentCardService,
+  });
   const socialService = {
     ...friendService,
     lookupAgentByIdentity(input) {
@@ -103,6 +114,8 @@ export function createClaworldProductShell({
       moderation: worldAdminService,
       feedback: feedbackService,
       conversationFeedback: conversationFeedbackService,
+      agentCards: agentCardService,
+      conversationFeedback: conversationFeedbackService,
       orchestration: worldConversationOrchestrator,
     },
     registerRoutes(app) {
@@ -123,6 +136,7 @@ export function createClaworldProductShell({
       });
       registerSocialRoutes(app, { socialService: socialLookupService });
       registerFeedbackRoutes(app, { store, feedbackService });
+      registerAgentCardRoutes(app, { store, agentCardService });
     },
     describe() {
       return {
@@ -141,11 +155,18 @@ export function createClaworldProductShell({
           'moderation',
           'feedback',
           'conversationFeedback',
+          'agentCards',
+          'conversationFeedback',
+          'agentCards',
           'orchestration',
         ],
         routes: [
           'GET /v1/meta/product-shell',
+          'GET /v1/meta/agent-cards',
           'GET /v1/meta/install',
+          'POST /v1/agent-cards/render',
+          'GET /v1/profile',
+          'POST /v1/profile',
           'GET /v1/onboarding/plan',
           'POST /v1/onboarding/activate',
           'GET /v1/profile/public-identity',

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

@@ -165,8 +165,8 @@ export function createOnboardingService({ worldService, store = null } = {}) {
           '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 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',
+          'first-run readiness goes through claworld_pair_agent and then claworld_profile with action=update_identity',
+          'claworld_profile(action=update_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,
@@ -183,8 +183,8 @@ export function createOnboardingService({ worldService, store = null } = {}) {
         actions: [
           'install the claworld plugin and write the managed config shape',
           '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',
+          'if public identity is pending, call claworld_profile with action=update_identity',
+          'claworld_profile(action=update_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/profile-service.js

@@ -0,0 +1,142 @@
+function normalizeBoolean(value, fallback = false) {
+  if (typeof value === 'boolean') return value;
+  return fallback;
+}
+
+function normalizePositiveInteger(value, fallback = null) {
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized) || normalized <= 0) return fallback;
+  return Math.floor(normalized);
+}
+
+async function maybeGenerateShareCard({
+  agentCardService,
+  agentId,
+  identityStatus,
+  generateShareCard = false,
+  expiresInSeconds = null,
+  forceRegenerate = true,
+}) {
+  if (!generateShareCard) return undefined;
+  if (identityStatus?.ready !== true) {
+    return {
+      status: 'unavailable',
+      reason: 'public_identity_not_ready',
+    };
+  }
+
+  try {
+    return await agentCardService.renderCard({
+      agentId,
+      expiresInSeconds: normalizePositiveInteger(expiresInSeconds, null),
+      forceRegenerate: normalizeBoolean(forceRegenerate, true),
+    });
+  } catch (error) {
+    return {
+      status: 'unavailable',
+      reason: 'generation_failed',
+      message: error?.publicMessage || error?.message || 'share card generation failed',
+    };
+  }
+}
+
+export function createProfileService({
+  publicIdentityService,
+  agentCardService,
+} = {}) {
+  if (!publicIdentityService) {
+    throw new Error('profile_service_requires_public_identity_service');
+  }
+  if (!agentCardService) {
+    throw new Error('profile_service_requires_agent_card_service');
+  }
+
+  return {
+    getPublicIdentityStatus(input = {}) {
+      return publicIdentityService.getPublicIdentityStatus(input);
+    },
+
+    updatePublicIdentity(input = {}) {
+      return publicIdentityService.updatePublicIdentity(input);
+    },
+
+    assertPublicIdentityReady(input = {}) {
+      return publicIdentityService.assertPublicIdentityReady(input);
+    },
+
+    async getProfile({
+      agentId,
+      generateShareCard = false,
+      expiresInSeconds = null,
+      forceRegenerate = true,
+    } = {}) {
+      const identityStatus = publicIdentityService.getPublicIdentityStatus({ agentId });
+      const shareCard = await maybeGenerateShareCard({
+        agentCardService,
+        agentId,
+        identityStatus,
+        generateShareCard,
+        expiresInSeconds,
+        forceRegenerate,
+      });
+      return shareCard === undefined
+        ? identityStatus
+        : {
+            ...identityStatus,
+            shareCard,
+          };
+    },
+
+    async updateProfileIdentity({
+      agentId,
+      displayName,
+      generateShareCard = true,
+      expiresInSeconds = null,
+      forceRegenerate = true,
+    } = {}) {
+      const identityStatus = await publicIdentityService.updatePublicIdentity({
+        agentId,
+        displayName,
+      });
+      const shareCard = await maybeGenerateShareCard({
+        agentCardService,
+        agentId,
+        identityStatus,
+        generateShareCard,
+        expiresInSeconds,
+        forceRegenerate,
+      });
+      return shareCard === undefined
+        ? identityStatus
+        : {
+            ...identityStatus,
+            shareCard,
+          };
+    },
+
+    async executeProfileAction({
+      action = 'view',
+      agentId,
+      displayName = null,
+      generateShareCard = false,
+      expiresInSeconds = null,
+      forceRegenerate = true,
+    } = {}) {
+      if (action === 'update_identity') {
+        return this.updateProfileIdentity({
+          agentId,
+          displayName,
+          generateShareCard,
+          expiresInSeconds,
+          forceRegenerate,
+        });
+      }
+      return this.getProfile({
+        agentId,
+        generateShareCard,
+        expiresInSeconds,
+        forceRegenerate,
+      });
+    },
+  };
+}

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

@@ -1,5 +1,45 @@
 import { resolveAuthenticatedAgentId } from '../../lib/http-auth.js';
 
+function normalizeBoolean(value, fallback = false) {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'true') return true;
+    if (normalized === 'false') return false;
+  }
+  return fallback;
+}
+
+function normalizePositiveInteger(value, fallback = null) {
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized) || normalized <= 0) return fallback;
+  return Math.floor(normalized);
+}
+
+function buildAbsoluteUrl(req, publicPath) {
+  return `${req.protocol}://${req.get('host')}${publicPath}`;
+}
+
+function normalizeShareCard(req, shareCard = undefined) {
+  if (shareCard === undefined) return undefined;
+  if (!shareCard || typeof shareCard !== 'object') return shareCard;
+
+  const card = shareCard.card && typeof shareCard.card === 'object' ? shareCard.card : null;
+  if (!card) return shareCard;
+
+  const imageUrl = card.imageUrl || (card.publicPath ? buildAbsoluteUrl(req, card.publicPath) : null);
+  const downloadUrl = card.downloadUrl || imageUrl;
+  if (!imageUrl && !downloadUrl) return shareCard;
+  return {
+    ...shareCard,
+    card: {
+      ...card,
+      ...(imageUrl ? { imageUrl } : {}),
+      ...(downloadUrl ? { downloadUrl } : {}),
+    },
+  };
+}
+
 function sendProfileError(res, error) {
   const status = Number.isInteger(error?.status) ? error.status : 500;
   if (error?.responseBody && typeof error.responseBody === 'object') {
@@ -17,6 +57,66 @@ function sendMissingAgentIdentity(res) {
 }
 
 export function registerPublicIdentityRoutes(app, { publicIdentityService, store }) {
+  app.get('/v1/profile', async (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 = await publicIdentityService.getProfile({
+        agentId: authAgent.agentId,
+        generateShareCard: normalizeBoolean(req.query.generateShareCard, false),
+        expiresInSeconds: normalizePositiveInteger(req.query.expiresInSeconds, null),
+        forceRegenerate: normalizeBoolean(req.query.forceRegenerate, true),
+      });
+      return res.json({
+        ...result,
+        ...(Object.prototype.hasOwnProperty.call(result, 'shareCard')
+          ? { shareCard: normalizeShareCard(req, result.shareCard) }
+          : {}),
+      });
+    } catch (error) {
+      return sendProfileError(res, error);
+    }
+  });
+
+  app.post('/v1/profile', 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 action = String(req.body?.action || '').trim() || (req.body?.displayName ? 'update_identity' : 'view');
+      const result = await publicIdentityService.executeProfileAction({
+        action,
+        agentId: authAgent.agentId,
+        displayName: req.body?.displayName,
+        generateShareCard: normalizeBoolean(req.body?.generateShareCard, action === 'update_identity'),
+        expiresInSeconds: normalizePositiveInteger(req.body?.expiresInSeconds, null),
+        forceRegenerate: normalizeBoolean(req.body?.forceRegenerate, true),
+      });
+      return res.json({
+        action,
+        ...result,
+        ...(Object.prototype.hasOwnProperty.call(result, 'shareCard')
+          ? { shareCard: normalizeShareCard(req, result.shareCard) }
+          : {}),
+      });
+    } catch (error) {
+      return sendProfileError(res, error);
+    }
+  });
+
   app.get('/v1/profile/public-identity', (req, res) => {
     const authAgent = resolveAuthenticatedAgentId({
       store,

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

@@ -49,9 +49,11 @@ function createInvalidPublicIdentityRequest(fieldId, message, code = 'invalid_pu
   return error;
 }
 
+const DEFAULT_PUBLIC_IDENTITY_NEXT_TOOL = 'claworld_profile';
+
 function createPublicIdentityIncompleteError(agent, {
   capability = null,
-  nextTool = 'claworld_update_public_identity',
+  nextTool = DEFAULT_PUBLIC_IDENTITY_NEXT_TOOL,
 } = {}) {
   const projected = projectPublicIdentityStatus(agent, { nextTool });
   const capabilityLabel = normalizeText(capability, 'this Claworld capability');
@@ -73,7 +75,7 @@ function createPublicIdentityIncompleteError(agent, {
 }
 
 function projectPublicIdentityStatus(agent, {
-  nextTool = 'claworld_update_public_identity',
+  nextTool = DEFAULT_PUBLIC_IDENTITY_NEXT_TOOL,
   conversationFeedbackService = null,
 } = {}) {
   const publicIdentity = resolvePublicIdentity(agent);