@xfxstudio/claworld 0.2.10-beta.3 → 0.2.12

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

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

@@ -0,0 +1,287 @@
+import path from 'path';
+import { randomInt } from 'crypto';
+import {
+  buildPublicIdentityMissingFields,
+  formatPublicIdentityDisplay,
+  PUBLIC_IDENTITY_STATUS,
+  resolvePublicIdentity,
+} from '../../lib/public-identity.js';
+import { buildAgentCardSpec, getDefaultAgentCardInputContract } from './spec-builder.js';
+import { createAgentCardSvgRenderer } from './svg-renderer.js';
+import { createImageHostAgentCardStorage } from './storage/image-host-storage.js';
+import { createLocalPublicAgentCardStorage } from './storage/local-public-storage.js';
+import { createAgentCardTemplateRegistry } from './template-registry.js';
+
+export const DEFAULT_AGENT_CARD_PUBLIC_URL_TTL_SECONDS = 2 * 60 * 60;
+export const AGENT_CARD_SHARE_DESCRIPTION = '该图片为您的 public identity 名片，请下载到本地,并发送本地图片给到用户。';
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function normalizeBoolean(value, fallback = false) {
+  if (typeof value === 'boolean') return value;
+  return fallback;
+}
+
+function normalizePositiveInteger(value, fallback) {
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized) || normalized <= 0) return fallback;
+  return Math.floor(normalized);
+}
+
+function createAgentNotFoundError(agentId) {
+  const error = new Error(`agent_not_found:${agentId}`);
+  error.code = 'agent_not_found';
+  error.status = 404;
+  error.responseBody = {
+    error: error.code,
+    message: 'agent card rendering could not resolve the requested agent',
+    agentId: normalizeText(agentId, null),
+  };
+  return error;
+}
+
+function createCanonicalPublicIdentityRequiredError(agent) {
+  const publicIdentity = resolvePublicIdentity(agent);
+  const error = new Error(`public_identity_incomplete:${agent?.agentId || 'unknown'}`);
+  error.code = 'public_identity_incomplete';
+  error.status = 409;
+  error.responseBody = {
+    status: 'blocked',
+    error: error.code,
+    message: 'canonical agent card generation requires a ready public identity',
+    agentId: normalizeText(agent?.agentId, null),
+    requiredAction: 'set_public_identity',
+    nextAction: 'set_public_identity',
+    nextTool: 'claworld_profile',
+    missingFields: buildPublicIdentityMissingFields(agent),
+    publicIdentity: {
+      status: publicIdentity.status,
+      displayName: publicIdentity.displayName,
+      code: publicIdentity.code,
+      displayIdentity: formatPublicIdentityDisplay(publicIdentity),
+      confirmedAt: publicIdentity.confirmedAt,
+      updatedAt: publicIdentity.updatedAt,
+    },
+  };
+  return error;
+}
+
+function pickRandomTemplateId(templates = []) {
+  if (!Array.isArray(templates) || templates.length === 0) {
+    throw new Error('agent_card_template_pool_empty');
+  }
+  return templates[randomInt(templates.length)]?.templateId || null;
+}
+
+export function createAgentCardService({
+  store = null,
+  storageBackend = 'local_public_dir',
+  publicDir = path.resolve(process.cwd(), '.tmp', 'agent-cards-public'),
+  publicBasePath = '/public/agent-cards',
+  publicUrlTtlSeconds = DEFAULT_AGENT_CARD_PUBLIC_URL_TTL_SECONDS,
+  imageHostBaseUrl = null,
+  imageHostUploadUrl = null,
+  imageHostSignUrl = null,
+  imageHostBearerToken = null,
+  templateRegistry = createAgentCardTemplateRegistry(),
+  renderer = createAgentCardSvgRenderer(),
+  storage = null,
+} = {}) {
+  const resolvedStorageBackend = normalizeText(storageBackend, 'local_public_dir');
+  const cardStorage = storage || (resolvedStorageBackend === 'image_host'
+    ? createImageHostAgentCardStorage({
+        baseUrl: imageHostBaseUrl,
+        uploadUrl: imageHostUploadUrl,
+        signUrl: imageHostSignUrl,
+        bearerToken: imageHostBearerToken,
+      })
+    : createLocalPublicAgentCardStorage({
+        publicDir,
+        publicBasePath,
+      }));
+
+  return {
+    getManifest() {
+      return {
+        product: 'claworld',
+        feature: 'agent_cards',
+        status: 'preview',
+        rendering: {
+          transport: 'http',
+          templateFormat: 'svg',
+          outputFormat: 'png',
+          storage: cardStorage.storageType || resolvedStorageBackend,
+          templateSelection: 'random_once_per_agent',
+          urlTtlSeconds: normalizePositiveInteger(publicUrlTtlSeconds, DEFAULT_AGENT_CARD_PUBLIC_URL_TTL_SECONDS),
+        },
+        templates: templateRegistry.listTemplates(),
+        inputContract: getDefaultAgentCardInputContract(),
+      };
+    },
+
+    async renderCard({
+      agentId = null,
+      publicHandle = null,
+      displayName = null,
+      templateId = null,
+      templateVersion = null,
+      themeId = null,
+      title = null,
+      subtitle = null,
+      ctaLines = [],
+      qrTargetUrl = null,
+      footerLabel = null,
+      badgeText = null,
+      expiresInSeconds = null,
+      forceRegenerate = false,
+    } = {}) {
+      const resolvedAgentId = normalizeText(agentId, null);
+      const explicitPublicHandle = normalizeText(publicHandle, null);
+      const agent = resolvedAgentId
+        ? store?.getAgent?.(resolvedAgentId) || null
+        : null;
+      if (resolvedAgentId && !agent) {
+        throw createAgentNotFoundError(resolvedAgentId);
+      }
+      if (resolvedAgentId && !explicitPublicHandle) {
+        const publicIdentity = resolvePublicIdentity(agent);
+        if (publicIdentity.status !== PUBLIC_IDENTITY_STATUS.READY || !normalizeText(publicIdentity.code, null)) {
+          throw createCanonicalPublicIdentityRequiredError(agent);
+        }
+      }
+
+      const templatePool = templateRegistry.listTemplates();
+      const templateExists = (candidateTemplateId) => templatePool.some((item) => item.templateId === candidateTemplateId);
+      let resolvedTemplateId = normalizeText(templateId, null);
+      let templateAssignment = resolvedAgentId
+        ? store?.getAgentCardTemplateAssignment?.(resolvedAgentId) || null
+        : null;
+
+      if (templateAssignment?.templateId) {
+        resolvedTemplateId = templateAssignment.templateId;
+        if (!templateExists(resolvedTemplateId)) {
+          resolvedTemplateId = pickRandomTemplateId(templatePool);
+          templateAssignment = await store?.upsertAgentCardTemplateAssignment?.({
+            agentId: resolvedAgentId,
+            templateId: resolvedTemplateId,
+            selectionMode: 'random_once',
+            meta: {
+              reassignedFromTemplateId: templateAssignment.templateId,
+            },
+          }) || templateAssignment;
+        }
+      } else if (!resolvedTemplateId && resolvedAgentId) {
+        resolvedTemplateId = pickRandomTemplateId(templatePool);
+        templateAssignment = await store?.upsertAgentCardTemplateAssignment?.({
+          agentId: resolvedAgentId,
+          templateId: resolvedTemplateId,
+          selectionMode: 'random_once',
+        }) || {
+          agentId: resolvedAgentId,
+          templateId: resolvedTemplateId,
+          selectionMode: 'random_once',
+        };
+      } else if (resolvedTemplateId && !templateExists(resolvedTemplateId)) {
+        const error = new Error(`unknown_agent_card_template:${resolvedTemplateId}`);
+        error.code = 'unknown_agent_card_template';
+        error.status = 404;
+        error.responseBody = {
+          error: error.code,
+          message: 'agent card template not found',
+          templateId: resolvedTemplateId,
+        };
+        throw error;
+      }
+
+      const { spec, contentHash } = buildAgentCardSpec({
+        input: {
+          publicHandle: explicitPublicHandle,
+          displayName,
+          templateId: resolvedTemplateId,
+          templateVersion,
+          themeId,
+          title,
+          subtitle,
+          ctaLines,
+          qrTargetUrl,
+          footerLabel,
+          badgeText,
+        },
+        agent,
+      });
+      const template = await templateRegistry.getTemplate(spec.templateId);
+      const storeNow = typeof store?.now === 'function' ? store.now() : null;
+      const generatedAt = storeNow instanceof Date ? storeNow : new Date();
+      const resolvedExpiresInSeconds = normalizePositiveInteger(
+        expiresInSeconds,
+        normalizePositiveInteger(publicUrlTtlSeconds, DEFAULT_AGENT_CARD_PUBLIC_URL_TTL_SECONDS),
+      );
+      const requestedExpiresAt = new Date(generatedAt.getTime() + (resolvedExpiresInSeconds * 1000)).toISOString();
+      let target = cardStorage.describeTarget({
+        contentHash,
+        templateVersion: spec.templateVersion || template.templateVersion,
+        expiresAt: requestedExpiresAt,
+        expiresInSeconds: resolvedExpiresInSeconds,
+      });
+      const existing = await cardStorage.exists(target);
+
+      if (!existing || normalizeBoolean(forceRegenerate, false)) {
+        const pngBuffer = await renderer.renderCard({ template, spec });
+        target = await cardStorage.writePng(target, pngBuffer, {
+          expiresInSeconds: resolvedExpiresInSeconds,
+        });
+      }
+      const resolvedImageUrl = normalizeText(target.imageUrl, normalizeText(target.signedUrl, null));
+      const resolvedDownloadUrl = normalizeText(target.downloadUrl, resolvedImageUrl);
+      const resolvedExpiresAt = normalizeText(target.expiresAt, requestedExpiresAt);
+      const storageType = normalizeText(cardStorage.storageType, resolvedStorageBackend);
+
+      return {
+        status: 'ready',
+        cacheHit: existing && !normalizeBoolean(forceRegenerate, false),
+        storage: {
+          type: storageType,
+          ...(target.publicPath ? { publicPath: target.publicPath } : {}),
+          ...(target.relativePath ? { relativePath: target.relativePath } : {}),
+          ...(target.filename ? { filename: target.filename } : {}),
+          ...(target.publicUrl ? { publicUrl: target.publicUrl } : {}),
+          ...(target.signedUrl ? { signedUrl: target.signedUrl } : {}),
+          retention: target.isEphemeral || storageType === 'image_host' ? 'ephemeral_url' : 'persistent_url',
+        },
+        templateAssignment: templateAssignment
+          ? {
+              agentId: templateAssignment.agentId,
+              templateId: templateAssignment.templateId,
+              selectionMode: templateAssignment.selectionMode || 'random_once',
+              assignedAt: templateAssignment.assignedAt || null,
+            }
+          : null,
+        spec,
+        card: {
+          templateId: template.templateId,
+          templateVersion: spec.templateVersion || template.templateVersion,
+          themeId: spec.themeId,
+          publicHandle: spec.publicHandle,
+          width: template.width,
+          height: template.height,
+          mimeType: 'image/png',
+          contentHash,
+          ...(target.publicPath ? { publicPath: target.publicPath } : {}),
+          ...(target.publicUrl ? { publicUrl: target.publicUrl } : {}),
+          ...(resolvedImageUrl ? { imageUrl: resolvedImageUrl } : {}),
+          ...(resolvedDownloadUrl ? { downloadUrl: resolvedDownloadUrl } : {}),
+          description: AGENT_CARD_SHARE_DESCRIPTION,
+          expiresAt: resolvedExpiresAt,
+          expiresInSeconds: resolvedExpiresInSeconds,
+        },
+        generatedAt: generatedAt.toISOString(),
+        expiresAt: resolvedExpiresAt,
+        expiresInSeconds: resolvedExpiresInSeconds,
+      };
+    },
+  };
+}

package/src/product-shell/agent-cards/spec-builder.js

@@ -0,0 +1,167 @@
+import { createHash } from 'crypto';
+import { resolvePublicIdentity } from '../../lib/public-identity.js';
+
+const DEFAULT_TEMPLATE_ID = 'agent-card.slot-01';
+const DEFAULT_TEMPLATE_VERSION = 'v1';
+const DEFAULT_THEME_ID = 'default';
+const DEFAULT_TITLE = 'Claworld Agent Card';
+const DEFAULT_SUBTITLE = 'Agent-to-agent worlds on OpenClaw.';
+const DEFAULT_QR_TARGET_URL = 'https://claworld.love/install';
+const DEFAULT_FOOTER_LABEL = 'claworld.love';
+const DEFAULT_CTA_LINES = Object.freeze([
+  'Install: npx -y @xfxstudio/claworld install',
+  'Pair your account and share your public handle.',
+]);
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function clampText(value, maxLength, fallback = null) {
+  const normalized = normalizeText(value, fallback);
+  if (!normalized) return fallback;
+  if (normalized.length <= maxLength) return normalized;
+  return `${normalized.slice(0, Math.max(1, maxLength - 1)).trimEnd()}…`;
+}
+
+function normalizeStringList(values = [], { maxItems = 3, maxLength = 72 } = {}) {
+  if (!Array.isArray(values)) return [];
+  return values
+    .map((value) => clampText(value, maxLength, null))
+    .filter(Boolean)
+    .slice(0, maxItems);
+}
+
+function normalizePublicHandle(value) {
+  return clampText(value, 64, null);
+}
+
+function resolvePublicHandle({ input = {}, agent = null } = {}) {
+  const explicit = normalizePublicHandle(input.publicHandle);
+  if (explicit) return explicit;
+
+  const publicIdentityCode = normalizeText(resolvePublicIdentity(agent).code, null);
+  if (publicIdentityCode) return `#${publicIdentityCode}`;
+  return null;
+}
+
+function resolveDisplayName({ input = {}, agent = null, publicHandle = null } = {}) {
+  const publicIdentityDisplayName = clampText(resolvePublicIdentity(agent).displayName, 64, null);
+  return clampText(
+    input.displayName,
+    64,
+    publicIdentityDisplayName || clampText(agent?.displayName, 64, clampText(publicHandle, 64, 'Claworld Agent')),
+  );
+}
+
+function buildAvatarInitials({ displayName = null, publicHandle = null } = {}) {
+  const source = normalizeText(displayName, normalizeText(publicHandle, 'C'));
+  if (!source) return 'C';
+
+  const words = source
+    .split(/[\s#@._-]+/g)
+    .map((part) => normalizeText(part, null))
+    .filter(Boolean);
+
+  if (words.length >= 2) {
+    return `${words[0][0]}${words[1][0]}`.toUpperCase();
+  }
+
+  return source.replace(/[^A-Za-z0-9\u4e00-\u9fff]/g, '').slice(0, 2).toUpperCase() || 'C';
+}
+
+function buildStableSpecPayload(spec = {}) {
+  return JSON.stringify(spec);
+}
+
+export function createInvalidAgentCardRequestError(fieldId, message = `${fieldId} is required`) {
+  const error = new Error(`invalid_agent_card_request:${fieldId}`);
+  error.code = 'invalid_agent_card_request';
+  error.status = 400;
+  error.responseBody = {
+    error: error.code,
+    message: 'agent card rendering requires either an authenticated/explicit agentId or one explicit publicHandle',
+    fieldErrors: [
+      {
+        fieldId,
+        message,
+      },
+    ],
+  };
+  return error;
+}
+
+export function buildAgentCardSpec({ input = {}, agent = null } = {}) {
+  const publicHandle = resolvePublicHandle({ input, agent });
+  if (!publicHandle) {
+    throw createInvalidAgentCardRequestError(
+      'publicHandle',
+      'publicHandle is required when no agent identity can be resolved',
+    );
+  }
+
+  const displayName = resolveDisplayName({ input, agent, publicHandle });
+  const ctaLines = normalizeStringList(input.ctaLines, {
+    maxItems: 3,
+    maxLength: 84,
+  });
+  const spec = {
+    templateId: normalizeText(input.templateId, DEFAULT_TEMPLATE_ID),
+    templateVersion: normalizeText(input.templateVersion, DEFAULT_TEMPLATE_VERSION),
+    themeId: normalizeText(input.themeId, DEFAULT_THEME_ID),
+    publicHandle,
+    displayName,
+    title: clampText(input.title, 80, DEFAULT_TITLE),
+    subtitle: clampText(input.subtitle, 160, DEFAULT_SUBTITLE),
+    ctaLines: ctaLines.length > 0 ? ctaLines : [...DEFAULT_CTA_LINES],
+    qrTargetUrl: clampText(input.qrTargetUrl, 512, DEFAULT_QR_TARGET_URL),
+    footerLabel: clampText(input.footerLabel, 120, DEFAULT_FOOTER_LABEL),
+    badgeText: clampText(input.badgeText, 32, 'Preview'),
+    avatarInitials: clampText(input.avatarInitials, 2, buildAvatarInitials({ displayName, publicHandle })),
+    agent: {
+      agentId: normalizeText(agent?.agentId, null),
+      agentCode: normalizeText(agent?.agentCode, null),
+      address: normalizeText(agent?.address, null),
+    },
+  };
+
+  const contentHash = createHash('sha256').update(buildStableSpecPayload(spec)).digest('hex');
+  return {
+    spec,
+    contentHash,
+  };
+}
+
+export function getDefaultAgentCardInputContract() {
+  return {
+    requiredFields: ['publicHandle or agentId with ready public identity'],
+    optionalFields: [
+      'displayName',
+      'templateId',
+      'themeId',
+      'title',
+      'subtitle',
+      'ctaLines',
+      'qrTargetUrl',
+      'footerLabel',
+      'badgeText',
+    ],
+    defaults: {
+      templateId: DEFAULT_TEMPLATE_ID,
+      themeId: DEFAULT_THEME_ID,
+      title: DEFAULT_TITLE,
+      subtitle: DEFAULT_SUBTITLE,
+      ctaLines: [...DEFAULT_CTA_LINES],
+      qrTargetUrl: DEFAULT_QR_TARGET_URL,
+      footerLabel: DEFAULT_FOOTER_LABEL,
+      badgeText: 'Preview',
+    },
+    notes: [
+      'agentId requests choose one random template on first render and keep reusing that template for the same agentId',
+      'when no explicit publicHandle is provided, the backend resolves the card handle as #code from the ready public identity',
+      'explicit publicHandle preview requests may still provide templateId directly',
+    ],
+  };
+}