@xfxstudio/claworld 0.2.11 → 0.2.13

package/src/openclaw/plugin/onboarding.js

@@ -1,6 +1,5 @@
 import {
   DEFAULT_CLAWORLD_ACCOUNT_ID,
-  DEFAULT_CLAWORLD_SERVER_URL,
   applyClaworldManagedRuntimeConfig,
   ensureObject,
   normalizeText,
@@ -11,15 +10,11 @@ import {
   inspectClaworldChannelAccount,
   listClaworldAccountIds,
 } from './config-schema.js';
-import {
-  buildManagedOnboardingStatus as buildClaworldOnboardingStatus,
-  inspectManagedClaworldInstall,
-  seedManagedWorkspace as ensureManagedWorkspaceSeed,
-} from '../installer/core.js';
 
 function collectUnsupportedSetupFlags(input = {}) {
   const unsupported = [];
   const flagMap = [
+    ['appToken', '--app-token'],
     ['token', '--token'],
     ['tokenFile', '--token-file'],
     ['botToken', '--bot-token'],
@@ -54,89 +49,143 @@ function collectUnsupportedSetupFlags(input = {}) {
   return unsupported;
 }
 
-function validateClaworldSetupInput({ cfg = {}, accountId = null, input = {} } = {}) {
+export function validateClaworldSetupInput({ input = {} } = {}) {
   const unsupportedFlags = collectUnsupportedSetupFlags(input);
   if (unsupportedFlags.length > 0) {
     return (
-      'Claworld setup only supports --name, --http-url/--url, and --app-token. ' +
-      `Unsupported flag(s): ${unsupportedFlags.join(', ')}.`
+      'Claworld host-native setup only supports an optional local account label and --http-url/--url overrides. '
+      + `Unsupported flag(s): ${unsupportedFlags.join(', ')}.`
     );
   }
 
-  const inspected = inspectClaworldChannelAccount(cfg, accountId);
-  const appToken = normalizeText(
-    input.appToken,
-    normalizeText(inspected?.appToken, null),
-  );
-
   const serverUrl = normalizeText(input.httpUrl, normalizeText(input.url, null));
-  if (serverUrl) {
-    try {
-      const parsed = new URL(serverUrl);
-      if (!['http:', 'https:', 'ws:', 'wss:'].includes(parsed.protocol)) {
-        return `Unsupported Claworld server URL protocol: ${parsed.protocol}`;
-      }
-    } catch {
-      return `Invalid Claworld server URL: ${serverUrl}`;
-    }
+  if (!serverUrl) {
+    return null;
   }
 
-  const registrationDisplayName = normalizeText(
-    input.name,
-    normalizeText(
-      inspected?.name,
-      normalizeText(
-        inspected?.registration?.displayName,
-        normalizeText(inspected?.localAgent?.displayName, null),
-      ),
-    ),
-  );
-  if (!appToken && !registrationDisplayName) {
-    return 'Claworld public display name is required unless you already have an appToken. Use --name <display-name> or --app-token <token>.';
+  try {
+    const parsed = new URL(serverUrl);
+    if (!['http:', 'https:', 'ws:', 'wss:'].includes(parsed.protocol)) {
+      return `Unsupported Claworld server URL protocol: ${parsed.protocol}`;
+    }
+  } catch {
+    return `Invalid Claworld server URL: ${serverUrl}`;
   }
 
   return null;
 }
 
-function currentManagedIdentityInput({ cfg = {}, accountId = null } = {}) {
-  const inspected = inspectClaworldChannelAccount(cfg, accountId);
-  const appToken = normalizeText(inspected?.appToken, null);
-  if (appToken) {
-    return {
-      appToken,
-    };
-  }
+function findAgentEntry(config = {}, agentId) {
+  const normalizedAgentId = normalizeText(agentId, null);
+  if (!normalizedAgentId) return null;
+  const list = Array.isArray(config?.agents?.list) ? config.agents.list : [];
+  return list
+    .map((entry) => ensureObject(entry))
+    .find((entry) => entry.id === normalizedAgentId) || null;
+}
 
-  const currentDisplayName = normalizeText(
-    inspected?.name,
-    normalizeText(
-      inspected?.registration?.displayName,
-      normalizeText(inspected?.localAgent?.displayName, null),
-    ),
+function hasClaworldBinding(config = {}, { agentId, accountId } = {}) {
+  const normalizedAgentId = normalizeText(agentId, null);
+  const normalizedAccountId = normalizeText(accountId, DEFAULT_CLAWORLD_ACCOUNT_ID);
+  const resolvedDefaultAccountId = defaultClaworldAccountId(config) || DEFAULT_CLAWORLD_ACCOUNT_ID;
+  const bindings = Array.isArray(config?.bindings) ? config.bindings : [];
+  return bindings.some((binding) => {
+    const candidate = ensureObject(binding);
+    const match = ensureObject(candidate.match);
+    const bindingChannel = normalizeText(match.channel, null);
+    const bindingAccountId = normalizeText(match.accountId, null);
+    const bindingAgentId = normalizeText(candidate.agentId, null);
+    if (bindingChannel !== 'claworld') return false;
+    if (normalizedAgentId && bindingAgentId !== normalizedAgentId) return false;
+    if (bindingAccountId === normalizedAccountId) return true;
+    return !bindingAccountId && resolvedDefaultAccountId === normalizedAccountId;
+  });
+}
+
+function isRelayBootstrapReady(account = {}) {
+  return Boolean(
+    account?.configured
+    && normalizeText(account?.appToken, null),
   );
-  return currentDisplayName
-    ? { name: currentDisplayName }
-    : {};
 }
 
-async function collectManagedIdentityInput({ cfg = {}, prompter, accountId = null } = {}) {
-  const currentInput = currentManagedIdentityInput({ cfg, accountId });
-  if (currentInput.appToken) {
-    return currentInput;
+export function inspectManagedClaworldInstall({
+  cfg = {},
+  accountId = DEFAULT_CLAWORLD_ACCOUNT_ID,
+  input = {},
+  overrides = {},
+} = {}) {
+  const configuredAccountIds = listClaworldAccountIds(cfg);
+  const hasAnyConfig = configuredAccountIds.length > 0 || cfg?.channels?.claworld != null;
+  const managedOptions = resolveClaworldManagedRuntimeOptions({
+    cfg,
+    accountId,
+    input,
+    overrides,
+  });
+  const managedAgentPresent = Boolean(findAgentEntry(cfg, managedOptions.agentId));
+  const managedBindingPresent = hasClaworldBinding(cfg, managedOptions);
+  const managedAccountPresent = configuredAccountIds.includes(managedOptions.accountId);
+  const accountStatus = managedAccountPresent
+    ? inspectClaworldChannelAccount(cfg, managedOptions.accountId)
+    : inspectClaworldChannelAccount({}, managedOptions.accountId);
+  const activationReady = isRelayBootstrapReady(accountStatus);
+  const setupReady = Boolean(
+    managedAccountPresent
+    && managedBindingPresent
+    && (managedOptions.manageAgentEntry !== true || managedAgentPresent)
+  );
+
+  let statusLabel = 'needs setup';
+  let selectionHint = 'remote relay world channel';
+  let quickstartScore = 5;
+
+  if (setupReady && activationReady) {
+    statusLabel = 'configured';
+    selectionHint = 'configured · ready';
+    quickstartScore = 2;
+  } else if (setupReady) {
+    statusLabel = 'configured (activation pending)';
+    selectionHint = 'configured · activation pending';
+    quickstartScore = 3;
+  } else if (managedAccountPresent && !managedBindingPresent) {
+    statusLabel = 'configured (binding pending)';
+    selectionHint = 'configured · binding pending';
+    quickstartScore = 4;
+  } else if (hasAnyConfig) {
+    statusLabel = 'configured (refresh recommended)';
+    selectionHint = 'configured · refresh recommended';
+    quickstartScore = 4;
   }
 
-  const name = await prompter.text({
-    message: 'Choose the public display name to bootstrap this Claworld agent',
-    initialValue: currentInput.name || '',
-    placeholder: 'Claworld Agent',
-    validate: (value) => {
-      const message = validateClaworldSetupInput({ input: { name: value } });
-      return message || undefined;
-    },
-  });
+  return {
+    hasAnyConfig,
+    configuredAccountIds,
+    defaultAccountId: defaultClaworldAccountId(cfg) || null,
+    managedOptions,
+    managedAccountPresent,
+    managedAgentPresent,
+    managedBindingPresent,
+    accountStatus,
+    activationReady,
+    setupReady,
+    statusLabel,
+    selectionHint,
+    quickstartScore,
+  };
+}
 
+export function buildClaworldOnboardingStatus({
+  cfg = {},
+  accountId = DEFAULT_CLAWORLD_ACCOUNT_ID,
+} = {}) {
+  const inspection = inspectManagedClaworldInstall({ cfg, accountId });
   return {
-    name,
+    configured: inspection.setupReady,
+    statusLines: [`Claworld: ${inspection.statusLabel}`],
+    selectionHint: inspection.selectionHint,
+    quickstartScore: inspection.quickstartScore,
+    activationReady: inspection.activationReady,
   };
 }
 
@@ -178,7 +227,7 @@ function resolveManagedOptionsFromContext({ cfg = {}, accountId = null, input =
     input: resolvedInput,
     overrides: {
       ...overrides,
-      ...(normalizeText(normalizedInput.name, null) ? { displayName: normalizedInput.name } : {}),
+      ...(normalizeText(normalizedInput.name, null) ? { name: normalizedInput.name } : {}),
     },
   });
 }
@@ -192,19 +241,14 @@ async function applyManagedOnboardingConfig({
 } = {}) {
   const managedOptions = resolveManagedOptionsFromContext({ cfg, accountId, input });
   const next = applyClaworldManagedRuntimeConfig(cfg, managedOptions);
-  if (managedOptions.manageWorkspace) {
-    await ensureManagedWorkspaceSeed(managedOptions);
-  }
 
   const noteLines = [
     `Bound local agent/account: ${managedOptions.agentId}`,
     `Remote backend: ${managedOptions.serverUrl}`,
     managedOptions.appToken
       ? 'Activation state: ready via configured appToken'
-      : 'Activation state: pending until claworld_update_public_identity 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.',
+      : 'Activation state: pending until claworld_profile(action=update_identity) runs',
+    'This flow refreshes plugin-side config and binds claworld onto the selected local agent. It does not run installer commands or start a backend service.',
   ];
   await prompter.note(
     noteLines.join('\n'),
@@ -230,7 +274,7 @@ export const claworldSetupAdapter = {
     return accountIds.length > 0 ? defaultClaworldAccountId(cfg) : DEFAULT_CLAWORLD_ACCOUNT_ID;
   },
   applyAccountName: ({ cfg, accountId, name }) => applyManagedAccountName({ cfg, accountId, name }),
-  validateInput: ({ cfg, accountId, input }) => validateClaworldSetupInput({ cfg, accountId, input }),
+  validateInput: ({ input }) => validateClaworldSetupInput({ input }),
   applyAccountConfig: ({ cfg, accountId, input }) => {
     const managedOptions = resolveManagedOptionsFromContext({ cfg, accountId, input });
     return applyClaworldManagedRuntimeConfig(cfg, managedOptions).config;
@@ -249,39 +293,20 @@ export const claworldOnboardingAdapter = {
       }),
     };
   },
-  configure: async ({ cfg, prompter, accountOverrides }) => {
-    const input = await collectManagedIdentityInput({
-      cfg,
-      prompter,
-      accountId: accountOverrides?.claworld,
-    });
-    return await applyManagedOnboardingConfig({
+  configure: async ({ cfg, prompter, accountOverrides }) =>
+    applyManagedOnboardingConfig({
       cfg,
       prompter,
       accountId: accountOverrides?.claworld,
       phase: 'setup',
-      input,
-    });
-  },
-  configureWhenConfigured: async ({ cfg, prompter, accountOverrides }) => {
-    const input = await collectManagedIdentityInput({
-      cfg,
-      prompter,
-      accountId: accountOverrides?.claworld,
-    });
-    return await applyManagedOnboardingConfig({
+      input: {},
+    }),
+  configureWhenConfigured: async ({ cfg, prompter, accountOverrides }) =>
+    applyManagedOnboardingConfig({
       cfg,
       prompter,
       accountId: accountOverrides?.claworld,
       phase: 'refresh',
-      input,
-    });
-  },
-};
-
-export {
-  buildClaworldOnboardingStatus,
-  ensureManagedWorkspaceSeed,
-  inspectManagedClaworldInstall,
-  validateClaworldSetupInput,
+      input: {},
+    }),
 };

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