@xfxstudio/claworld 0.2.11 → 0.2.12

package/openclaw.plugin.json

@@ -8,7 +8,7 @@
   ],
   "name": "Claworld Persona Relay",
   "description": "Claworld relay world channel plugin for OpenClaw.",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfxstudio/claworld",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "description": "Claworld channel plugin for OpenClaw",
   "type": "module",
   "main": "index.js",

package/src/openclaw/installer/cli.js

@@ -300,7 +300,7 @@ function printInstallSummary(result) {
   console.log(`Managed account:    ${result.transformed?.config?.channels?.claworld?.defaultAccount || 'claworld'}`);
   console.log(`OpenClaw version:   ${result.host?.version || '(unknown)'}`);
   console.log(`Plugin action:      ${result.plugin?.action || 'unknown'}`);
-  console.log(`Activation:         ${result.activationStatus === 'ready' ? 'ready' : 'pending via claworld_update_public_identity'}`);
+  console.log(`Activation:         ${result.activationStatus === 'ready' ? 'ready' : 'pending via claworld_profile'}`);
   console.log(`Runtime refresh:    ${result.runtimeRefresh?.action || 'unknown'}`);
   console.log(`Config path:        ${result.configPath}`);
   console.log(`Backup path:        ${result.backupPath || '(unchanged or new file)'}`);
@@ -319,7 +319,7 @@ function printUpdateSummary(result, doctorResult) {
   console.log(`OpenClaw version:   ${result.host?.version || '(unknown)'}`);
   console.log(`Plugin action:      ${result.plugin?.action || 'unknown'}`);
   console.log(`Tracked install:    ${trackedSummary}`);
-  console.log(`Activation:         ${result.activationStatus === 'ready' ? 'ready' : 'pending via claworld_update_public_identity'}`);
+  console.log(`Activation:         ${result.activationStatus === 'ready' ? 'ready' : 'pending via claworld_profile'}`);
   console.log(`Runtime refresh:    ${result.runtimeRefresh?.action || 'unknown'}`);
   console.log(`Doctor status:      ${doctorResult?.status || 'unknown'}`);
   console.log(`Config path:        ${result.configPath}`);

package/src/openclaw/installer/doctor.js

@@ -528,7 +528,7 @@ export async function runClaworldDoctor({
       : `Managed account token status is ${configuredAccount.tokenStatus}; activation is still pending.`,
     action: configuredAccount.tokenStatus === 'available'
       ? null
-      : 'Open a live OpenClaw session, run `claworld_pair_agent`, and then complete `claworld_update_public_identity` when prompted.',
+      : 'Open a live OpenClaw session, run `claworld_pair_agent`, and then complete `claworld_profile` with `action=update_identity` when prompted.',
     details: { tokenSource: configuredAccount.tokenSource, tokenStatus: configuredAccount.tokenStatus },
   }));
 
@@ -593,7 +593,7 @@ export async function runClaworldDoctor({
       label: 'Stable relay binding',
       status: 'warn',
       summary: 'Doctor could not verify the managed relay binding because activation is still pending.',
-      action: 'Open a live OpenClaw session, run `claworld_pair_agent`, and then complete `claworld_update_public_identity` when prompted.',
+      action: 'Open a live OpenClaw session, run `claworld_pair_agent`, and then complete `claworld_profile` with `action=update_identity` when prompted.',
     }));
   } else {
     checks.push(createCheck({
@@ -676,7 +676,7 @@ export async function runClaworldDoctor({
       action: channelHealthy
         ? null
         : channelPendingActivation
-          ? 'Open a live OpenClaw session, run `claworld_pair_agent`, and then complete `claworld_update_public_identity` when prompted.'
+          ? 'Open a live OpenClaw session, run `claworld_pair_agent`, and then complete `claworld_profile` with `action=update_identity` when prompted.'
           : `Rerun \`${CLAWORLD_INSTALLER_COMMAND}\` or restart the gateway to recover the managed account runtime.`,
       details: { channelAccount },
     }));

package/src/openclaw/plugin/claworld-channel-plugin.js

@@ -908,6 +908,8 @@ async function fetchJson(fetchImpl, url, init = {}) {
 async function fetchPublicIdentity({
   runtimeConfig,
   agentId = null,
+  generateShareCard = false,
+  expiresInSeconds = null,
   fetchImpl,
 }) {
   if (!resolveRuntimeAppToken(runtimeConfig)) {
@@ -930,7 +932,7 @@ async function fetchPublicIdentity({
       recommendedDisplayName,
       nextAction: 'set_public_identity',
       requiredAction: 'set_public_identity',
-      nextTool: 'claworld_update_public_identity',
+      nextTool: 'claworld_profile',
       missingFields: [
         {
           fieldId: 'displayName',
@@ -953,15 +955,21 @@ async function fetchPublicIdentity({
   }
 
   const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
-  const path = buildRelayJsonPath('/v1/profile/public-identity', {
-    agentId,
-  });
-  const result = await fetchJson(fetchImpl, `${baseUrl}${path}`, {
-    method: 'GET',
+  const result = await fetchJson(fetchImpl, `${baseUrl}/v1/profile`, {
+    method: 'POST',
     headers: {
+      'content-type': 'application/json',
       ...(runtimeConfig.apiKey ? { 'x-api-key': runtimeConfig.apiKey } : {}),
       ...buildRuntimeAuthHeaders(runtimeConfig),
     },
+    body: JSON.stringify({
+      ...(agentId ? { agentId } : {}),
+      action: 'view',
+      ...(generateShareCard === true ? { generateShareCard: true } : {}),
+      ...(normalizeClaworldInteger(expiresInSeconds, null) > 0
+        ? { expiresInSeconds: normalizeClaworldInteger(expiresInSeconds, null) }
+        : {}),
+    }),
   });
   if (!result.ok) {
     createRelayRouteError({
@@ -979,6 +987,8 @@ async function updatePublicIdentity({
   runtimeConfig,
   agentId = null,
   displayName = null,
+  generateShareCard = true,
+  expiresInSeconds = null,
   fetchImpl,
 }) {
   const normalizedDisplayName = normalizeClaworldText(displayName, null);
@@ -1039,8 +1049,8 @@ async function updatePublicIdentity({
     resolvedAgentId = activatedAgentId;
   }
   const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
-  const result = await fetchJson(fetchImpl, `${baseUrl}/v1/profile/public-identity`, {
-    method: 'PUT',
+  const result = await fetchJson(fetchImpl, `${baseUrl}/v1/profile`, {
+    method: 'POST',
     headers: {
       'content-type': 'application/json',
       ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
@@ -1048,7 +1058,12 @@ async function updatePublicIdentity({
     },
     body: JSON.stringify({
       ...(resolvedAgentId ? { agentId: resolvedAgentId } : {}),
+      action: 'update_identity',
       displayName: normalizedDisplayName,
+      ...(generateShareCard === true ? { generateShareCard: true } : {}),
+      ...(normalizeClaworldInteger(expiresInSeconds, null) > 0
+        ? { expiresInSeconds: normalizeClaworldInteger(expiresInSeconds, null) }
+        : {}),
     }),
   });
   if (!result.ok) {
@@ -1074,6 +1089,60 @@ async function updatePublicIdentity({
   };
 }
 
+async function renderAgentCard({
+  runtimeConfig,
+  agentId = null,
+  expiresInSeconds = null,
+  forceRegenerate = true,
+  fetchImpl,
+}) {
+  const resolvedAgentId = normalizeClaworldText(
+    agentId,
+    normalizeClaworldText(runtimeConfig?.relay?.agentId, null),
+  );
+  if (!resolvedAgentId) {
+    throw createRuntimeBoundaryError({
+      code: 'tool_input_invalid',
+      category: 'input',
+      status: 400,
+      message: 'claworld profile card rendering requires agentId',
+      publicMessage: 'claworld profile card rendering requires agentId',
+      recoverable: true,
+      context: { field: 'agentId' },
+    });
+  }
+
+  const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
+  const normalizedExpiresInSeconds = normalizeClaworldInteger(expiresInSeconds, null);
+  const result = await fetchJson(fetchImpl, `${baseUrl}/v1/agent-cards/render`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      ...(runtimeConfig.apiKey ? { 'x-api-key': runtimeConfig.apiKey } : {}),
+      ...buildRuntimeAuthHeaders(runtimeConfig),
+    },
+    body: JSON.stringify({
+      agentId: resolvedAgentId,
+      forceRegenerate: forceRegenerate === true,
+      ...(normalizedExpiresInSeconds && normalizedExpiresInSeconds > 0
+        ? { expiresInSeconds: normalizedExpiresInSeconds }
+        : {}),
+    }),
+  });
+  if (!result.ok) {
+    createRelayRouteError({
+      result,
+      runtimeConfig,
+      code: 'agent_card_render_failed',
+      publicMessage: 'failed to generate public identity card',
+      context: {
+        agentId: resolvedAgentId,
+      },
+    });
+  }
+  return result.body || {};
+}
+
 async function registerRelayBinding({ runtimeConfig, fetchImpl, logger }) {
   if (typeof fetchImpl !== 'function') {
     throw new Error('fetch is unavailable for relay registration');
@@ -2443,6 +2512,8 @@ export function createClaworldChannelPlugin({
     return fetchPublicIdentity({
       runtimeConfig: resolvedContext.runtimeConfig,
       agentId: resolvedContext.agentId || null,
+      generateShareCard: context.generateShareCard === true,
+      expiresInSeconds: context.expiresInSeconds ?? null,
       fetchImpl,
     });
   }
@@ -2453,6 +2524,8 @@ export function createClaworldChannelPlugin({
       runtimeConfig: resolvedContext.runtimeConfig,
       agentId: resolvedContext.agentId || null,
       displayName: context.displayName || null,
+      generateShareCard: context.generateShareCard !== false,
+      expiresInSeconds: context.expiresInSeconds ?? null,
       fetchImpl,
     });
 
@@ -2504,11 +2577,21 @@ export function createClaworldChannelPlugin({
     const payload = updateResult && typeof updateResult === 'object' && !Array.isArray(updateResult)
       ? { ...updateResult }
       : {};
-    delete payload.runtimeActivation;
     delete payload.runtimeConfig;
     return payload;
   }
 
+  async function generateRuntimeProfileCard(context = {}) {
+    const resolvedContext = await resolveBoundRuntimeContext(context);
+    return renderAgentCard({
+      runtimeConfig: resolvedContext.runtimeConfig,
+      agentId: context.agentId || resolvedContext.agentId || null,
+      expiresInSeconds: context.expiresInSeconds ?? null,
+      forceRegenerate: context.forceRegenerate !== false,
+      fetchImpl,
+    });
+  }
+
   return {
     id: 'claworld',
     meta: {
@@ -2763,6 +2846,7 @@ export function createClaworldChannelPlugin({
       profile: {
         getPublicIdentity: getRuntimePublicIdentity,
         updatePublicIdentity: updateRuntimePublicIdentity,
+        generateShareCard: generateRuntimeProfileCard,
       },
       postSetup: {
         fetchWorldDirectory: async (context = {}) => {
@@ -2917,6 +3001,7 @@ export function createClaworldChannelPlugin({
         profile: {
           getPublicIdentity: getRuntimePublicIdentity,
           updatePublicIdentity: updateRuntimePublicIdentity,
+          generateShareCard: generateRuntimeProfileCard,
         },
         fetchWorldDirectory: async (context = {}) => {
           const resolvedContext = await resolveBoundRuntimeContext(context);

package/src/openclaw/plugin/onboarding.js

@@ -201,7 +201,7 @@ async function applyManagedOnboardingConfig({
     `Remote backend: ${managedOptions.serverUrl}`,
     managedOptions.appToken
       ? 'Activation state: ready via configured appToken'
-      : 'Activation state: pending until claworld_update_public_identity runs',
+      : 'Activation state: pending until claworld_profile runs',
     managedOptions.manageWorkspace
       ? 'This flow refreshes plugin-side config and the dedicated claworld workspace contract. It does not start a backend service.'
       : 'This flow refreshes plugin-side config and binds claworld onto the existing local agent. It does not start a backend service.',

package/src/openclaw/plugin/register.js

@@ -239,6 +239,17 @@ function integerParam({
   };
 }
 
+function booleanParam({
+  description = null,
+  defaultValue = null,
+} = {}) {
+  return {
+    type: 'boolean',
+    ...(description ? { description } : {}),
+    ...(typeof defaultValue === 'boolean' ? { default: defaultValue } : {}),
+  };
+}
+
 function objectParam({
   description = null,
   properties = {},
@@ -337,6 +348,118 @@ function projectToolManageWorldActionResponse(payload = {}, { accountId = null,
   };
 }
 
+const PROFILE_ACTIONS = Object.freeze([
+  'view',
+  'update_identity',
+]);
+
+function normalizeProfileAction(value, fallback = null) {
+  const normalized = normalizeText(value, fallback);
+  return PROFILE_ACTIONS.includes(normalized) ? normalized : fallback;
+}
+
+function inferProfileAction(params = {}) {
+  const explicitAction = normalizeProfileAction(params.action, null);
+  if (explicitAction) return explicitAction;
+  if (normalizeText(params.displayName, null)) return 'update_identity';
+  return 'view';
+}
+
+function projectToolPublicIdentity(payload = null) {
+  if (!payload || typeof payload !== 'object') return null;
+  return {
+    status: payload.status || null,
+    ready: payload.ready ?? null,
+    publicIdentity: payload.publicIdentity && typeof payload.publicIdentity === 'object'
+      ? {
+          status: payload.publicIdentity.status || null,
+          displayIdentity: payload.publicIdentity.displayIdentity || null,
+          displayName: payload.publicIdentity.displayName || null,
+          code: payload.publicIdentity.code || null,
+          confirmedAt: payload.publicIdentity.confirmedAt || null,
+          updatedAt: payload.publicIdentity.updatedAt || null,
+        }
+      : null,
+    recommendedDisplayName: payload.recommendedDisplayName || null,
+    requiredAction: payload.requiredAction || null,
+    nextAction: payload.nextAction || null,
+    nextTool: payload.nextTool || null,
+    missingFields: Array.isArray(payload.missingFields) ? payload.missingFields : [],
+    feedbackSummary: payload.feedbackSummary && typeof payload.feedbackSummary === 'object'
+      ? {
+          totalLikesReceived: Number(payload.feedbackSummary.totalLikesReceived || 0),
+          totalDislikesReceived: Number(payload.feedbackSummary.totalDislikesReceived || 0),
+          totalLikesGiven: Number(payload.feedbackSummary.totalLikesGiven || 0),
+          totalDislikesGiven: Number(payload.feedbackSummary.totalDislikesGiven || 0),
+        }
+      : null,
+  };
+}
+
+function projectToolShareCard(payload = null) {
+  const card = payload?.card && typeof payload.card === 'object' ? payload.card : null;
+  const imageUrl = normalizeText(card?.imageUrl, normalizeText(payload?.imageUrl, null));
+  const downloadUrl = normalizeText(card?.downloadUrl, normalizeText(payload?.downloadUrl, imageUrl));
+  const templateId = normalizeText(card?.templateId, normalizeText(payload?.templateId, null));
+  const expiresAt = normalizeText(card?.expiresAt, normalizeText(payload?.expiresAt, null));
+  const description = normalizeText(card?.description, normalizeText(payload?.description, null));
+  if (!imageUrl && !downloadUrl && !templateId && !expiresAt && !description) {
+    return {
+      status: normalizeText(payload?.status, 'unavailable'),
+      reason: normalizeText(payload?.reason, null),
+      message: normalizeText(payload?.message, null),
+    };
+  }
+  return {
+    status: normalizeText(payload?.status, 'ready'),
+    imageUrl,
+    downloadUrl,
+    templateId,
+    expiresAt,
+    description,
+  };
+}
+
+function projectToolProfileResponse({
+  action = 'view',
+  accountId = null,
+  identityPayload = null,
+  shareCard = undefined,
+  runtimeActivation = null,
+} = {}) {
+  const projectedIdentity = projectToolPublicIdentity(identityPayload);
+  const resolvedShareCard = shareCard !== undefined
+    ? shareCard
+    : (identityPayload && Object.prototype.hasOwnProperty.call(identityPayload, 'shareCard')
+        ? projectToolShareCard(identityPayload.shareCard)
+        : undefined);
+  const ready = projectedIdentity?.ready === true;
+  return {
+    action,
+    status: ready ? 'ready' : 'pending',
+    ready,
+    accountId: normalizeText(accountId, null),
+    ...(projectedIdentity || {
+      publicIdentity: null,
+      recommendedDisplayName: null,
+      requiredAction: null,
+      nextAction: null,
+      nextTool: null,
+      missingFields: [],
+      feedbackSummary: null,
+    }),
+    ...(resolvedShareCard !== undefined ? { shareCard: resolvedShareCard } : {}),
+    ...(runtimeActivation ? { runtimeActivation } : {}),
+    ...(action === 'update_identity'
+      ? {
+          updated: resolvedShareCard && resolvedShareCard.status === 'ready'
+            ? ['publicIdentity', 'shareCard']
+            : ['publicIdentity'],
+        }
+      : {}),
+  };
+}
+
 function buildRegisteredTools(api, plugin) {
   const accountIdProperty = stringParam({
     description: 'Claworld account id to execute the tool against. In managed installs this is usually the dedicated claworld account.',
@@ -1145,7 +1268,7 @@ function buildRegisteredTools(api, plugin) {
           reason: payload.reason || null,
           requiredAction: publicIdentity?.requiredAction || (ready ? null : 'set_public_identity'),
           nextAction: publicIdentity?.nextAction || (ready ? 'continue_claworld_flow' : 'set_public_identity'),
-          nextTool: publicIdentity?.nextTool || (ready ? null : 'claworld_update_public_identity'),
+          nextTool: publicIdentity?.nextTool || (ready ? null : 'claworld_profile'),
           missingFields: Array.isArray(publicIdentity?.missingFields) ? publicIdentity.missingFields : [],
           accountId: payload.runtimeConfig?.accountId || accountId,
           bindingSource: payload.bindingSource || null,
@@ -1186,59 +1309,110 @@ function buildRegisteredTools(api, plugin) {
       },
     },
     {
-      name: 'claworld_get_public_identity',
-      label: 'Claworld Get Public Identity',
-      description: 'Read the current public identity state for the paired Claworld agent. Use this before world join or request-chat if you need to confirm whether public naming is complete.',
+      name: 'claworld_profile',
+      label: 'Claworld Profile',
+      description: 'View or update the paired Claworld public profile. This surface covers public identity readiness and, when requested, generates a temporary public identity card for sharing.',
       metadata: buildToolMetadata({
-        category: 'bootstrap',
+        category: 'profile',
         usageNotes: [
-          'Use when pair_agent indicates public identity is still pending.',
-          'Use before requesting a public-name confirmation from the user.',
+          'Default action is view; omit action to inspect the current public identity state.',
+          'Use action=update_identity after the user confirms a public-facing display name.',
+          'Set generateShareCard=true to return a temporary public identity card URL.',
         ],
-      }),
-      parameters: objectParam({
-        description: 'Read the current public identity state for one Claworld account.',
-        required: ['accountId'],
-        properties: {
-          accountId: accountIdProperty,
-        },
-      }),
-      async execute(_toolCallId, params = {}) {
-        const context = await resolveToolContext(api, plugin, params, { bindRuntime: false });
-        const payload = await plugin.runtime.productShell.profile.getPublicIdentity(context);
-        return buildToolResult(payload);
-      },
-    },
-    {
-      name: 'claworld_update_public_identity',
-      label: 'Claworld Update Public Identity',
-      description: 'Set or update the public display name for the paired Claworld agent. On first setup, the backend will generate a stable unique code and return the final displayName#code identity.',
-      metadata: buildToolMetadata({
-        category: 'bootstrap',
-        usageNotes: [
-          'Use after the user confirms a public-facing name.',
-          'On first setup, this generates the stable public code and completes identity readiness.',
+        examples: [
+          {
+            title: 'View the current profile state',
+            input: {
+              accountId: 'claworld',
+              action: 'view',
+            },
+            outcome: 'Returns the current public identity and readiness state.',
+          },
+          {
+            title: 'Update public identity and return a share card',
+            input: {
+              accountId: 'claworld',
+              action: 'update_identity',
+              displayName: '小发发',
+              generateShareCard: true,
+            },
+            outcome: 'Persists the display name, keeps the stable code, and returns a temporary share-card URL.',
+          },
         ],
       }),
       parameters: objectParam({
-        description: 'Update the public display name for one Claworld account.',
-        required: ['accountId', 'displayName'],
+        description: 'View or update the public profile for one Claworld account.',
+        required: ['accountId'],
         properties: {
           accountId: accountIdProperty,
+          action: stringParam({
+            description: 'Profile action. Defaults to view; inferred as update_identity when displayName is present.',
+            enumValues: PROFILE_ACTIONS,
+            examples: ['view', 'update_identity'],
+          }),
           displayName: stringParam({
-            description: 'Public-facing display name. # is reserved and must not appear here.',
+            description: 'Public-facing display name. Required for action=update_identity. # is reserved and must not appear here.',
             minLength: 1,
             examples: ['Moza', '小发发'],
           }),
+          generateShareCard: booleanParam({
+            description: 'When true, return a temporary public identity card URL. Defaults to false for view and true for update_identity.',
+          }),
+          expiresInSeconds: integerParam({
+            description: 'Optional temporary share-card TTL in seconds.',
+            minimum: 1,
+            examples: [7200],
+          }),
         },
+        examples: [
+          {
+            accountId: 'claworld',
+            action: 'view',
+          },
+          {
+            accountId: 'claworld',
+            action: 'update_identity',
+            displayName: '小发发',
+            generateShareCard: true,
+          },
+        ],
       }),
       async execute(_toolCallId, params = {}) {
         const context = await resolveToolContext(api, plugin, params, { bindRuntime: false });
-        const payload = await plugin.runtime.productShell.profile.updatePublicIdentity({
+        const action = inferProfileAction(params);
+        const generateShareCard = typeof params.generateShareCard === 'boolean'
+          ? params.generateShareCard
+          : action === 'update_identity';
+
+        if (action === 'update_identity') {
+          const displayName = normalizeText(params.displayName, null);
+          if (!displayName) {
+            requireManageWorldField('displayName', 'displayName is required for action=update_identity');
+          }
+          const payload = await plugin.runtime.productShell.profile.updatePublicIdentity({
+            ...context,
+            displayName,
+            generateShareCard,
+            expiresInSeconds: params.expiresInSeconds ?? null,
+          });
+          return buildToolResult(projectToolProfileResponse({
+            action,
+            accountId: context.accountId,
+            identityPayload: payload,
+            runtimeActivation: payload?.runtimeActivation || null,
+          }));
+        }
+
+        const payload = await plugin.runtime.productShell.profile.getPublicIdentity({
           ...context,
-          displayName: params.displayName,
+          generateShareCard,
+          expiresInSeconds: params.expiresInSeconds ?? null,
         });
-        return buildToolResult(payload);
+        return buildToolResult(projectToolProfileResponse({
+          action,
+          accountId: context.accountId,
+          identityPayload: payload,
+        }));
       },
     },
   ].map((tool) => ({

package/src/openclaw/runtime/tool-inventory.js

@@ -12,8 +12,7 @@ export const CLAWORLD_BOOTSTRAP_TOOL_NAMES = Object.freeze([
 ]);
 
 export const CLAWORLD_PROFILE_TOOL_NAMES = Object.freeze([
-  'claworld_get_public_identity',
-  'claworld_update_public_identity',
+  'claworld_profile',
 ]);
 
 export const CLAWORLD_FEEDBACK_TOOL_NAMES = Object.freeze([

package/src/product-shell/agent-cards/card-routes.js

@@ -0,0 +1,64 @@
+import { resolveAuthenticatedAgentId } from '../../lib/http-auth.js';
+
+function sendAgentCardError(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 buildAbsoluteUrl(req, publicPath) {
+  return `${req.protocol}://${req.get('host')}${publicPath}`;
+}
+
+export function registerAgentCardRoutes(app, { store, agentCardService }) {
+  app.get('/v1/meta/agent-cards', (_req, res) => {
+    res.json(agentCardService.getManifest());
+  });
+
+  app.post('/v1/agent-cards/render', async (req, res) => {
+    const resolvedAgent = resolveAuthenticatedAgentId({
+      store,
+      req,
+      providedAgentId: req.body?.agentId || null,
+      fieldName: 'agentId',
+    });
+    if (!resolvedAgent.ok) {
+      return res.status(resolvedAgent.status).json(resolvedAgent.body);
+    }
+
+    try {
+      const result = await agentCardService.renderCard({
+        agentId: resolvedAgent.agentId,
+        publicHandle: req.body?.publicHandle,
+        displayName: req.body?.displayName,
+        templateId: req.body?.templateId,
+        templateVersion: req.body?.templateVersion,
+        themeId: req.body?.themeId,
+        title: req.body?.title,
+        subtitle: req.body?.subtitle,
+        ctaLines: req.body?.ctaLines,
+        qrTargetUrl: req.body?.qrTargetUrl,
+        footerLabel: req.body?.footerLabel,
+        badgeText: req.body?.badgeText,
+        expiresInSeconds: req.body?.expiresInSeconds,
+        forceRegenerate: req.body?.forceRegenerate === true,
+      });
+
+      const imageUrl = result.card.imageUrl || (result.card.publicPath ? buildAbsoluteUrl(req, result.card.publicPath) : null);
+      const downloadUrl = result.card.downloadUrl || imageUrl;
+      return res.status(result.cacheHit ? 200 : 201).json({
+        ...result,
+        card: {
+          ...result.card,
+          ...(imageUrl ? { imageUrl } : {}),
+          ...(downloadUrl ? { downloadUrl } : {}),
+        },
+      });
+    } catch (error) {
+      return sendAgentCardError(res, error);
+    }
+  });
+}