@xfxstudio/claworld 2026.4.16-testing.1 → 2026.4.16-testing.2

package/src/lib/chat-request.js

@@ -0,0 +1,366 @@
+import { createKickoffBrief } from './relay/kickoff-text.js';
+import { normalizeAcceptedChatKickoffRecord } from './relay/kickoff-progress.js';
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function cloneJsonObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  try {
+    const cloned = JSON.parse(JSON.stringify(value));
+    if (!cloned || typeof cloned !== 'object' || Array.isArray(cloned)) return null;
+    return cloned;
+  } catch {
+    return null;
+  }
+}
+
+export function normalizeChatRequestConversation(input = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return {};
+  const conversation = {
+    ...(normalizeText(input.worldId, null) ? { worldId: normalizeText(input.worldId, null) } : {}),
+    ...(normalizeText(input.scope, null)
+      ? { scope: normalizeText(input.scope, null) }
+      : {}),
+    ...(normalizeText(input.conversationId, null) ? { conversationId: normalizeText(input.conversationId, null) } : {}),
+    ...(normalizeText(input.threadId, null) ? { threadId: normalizeText(input.threadId, null) } : {}),
+    ...(normalizeText(input.conversationKey, null) ? { conversationKey: normalizeText(input.conversationKey, null) } : {}),
+    ...(normalizeText(input.sessionKey, null) ? { sessionKey: normalizeText(input.sessionKey, null) } : {}),
+  };
+
+  const episode = cloneJsonObject(input.episode);
+  if (episode) {
+    conversation.episode = episode;
+  }
+  const worldContextText = normalizeText(
+    input.worldContextText,
+    normalizeText(input.worldContext?.worldContextText, normalizeText(input.worldContext?.text, null)),
+  );
+  if (worldContextText) {
+    conversation.worldContextText = worldContextText;
+  }
+
+  return conversation;
+}
+
+export function normalizeChatRequestOrigin(origin = {}, { fallbackType = null } = {}) {
+  if (!origin || typeof origin !== 'object' || Array.isArray(origin)) {
+    const type = normalizeText(fallbackType, null);
+    return type ? { type } : null;
+  }
+
+  const normalized = {
+    ...(normalizeText(origin.type, normalizeText(fallbackType, null))
+      ? { type: normalizeText(origin.type, normalizeText(fallbackType, null)) }
+      : {}),
+    ...(normalizeText(origin.broadcastId, null) ? { broadcastId: normalizeText(origin.broadcastId, null) } : {}),
+  };
+
+  return Object.keys(normalized).length > 0 ? normalized : null;
+}
+
+export function normalizeChatRequestBroadcast(input = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  const normalized = {
+    ...(normalizeText(input.broadcastId, null) ? { broadcastId: normalizeText(input.broadcastId, null) } : {}),
+    ...(normalizeText(input.worldId, null) ? { worldId: normalizeText(input.worldId, null) } : {}),
+    ...(normalizeText(input.audience, null) ? { audience: normalizeText(input.audience, null) } : {}),
+    ...(normalizeText(input.senderRole, null) ? { senderRole: normalizeText(input.senderRole, null) } : {}),
+    ...(normalizeText(input.eligibility, null) ? { eligibility: normalizeText(input.eligibility, null) } : {}),
+    ...(typeof input.excludeSelf === 'boolean' ? { excludeSelf: input.excludeSelf } : {}),
+  };
+  return Object.keys(normalized).length > 0 ? normalized : null;
+}
+
+export function normalizeChatRequestFollowUp(input = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  const normalized = {
+    ...(normalizeText(input.sessionKey, null) ? { sessionKey: normalizeText(input.sessionKey, null) } : {}),
+  };
+  return Object.keys(normalized).length > 0 ? normalized : null;
+}
+
+export function normalizeChatRequestOpeningPayload(input = null) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  const payload = cloneJsonObject(input);
+  if (!payload) return null;
+  if (typeof payload.text === 'string') {
+    payload.text = payload.text.trim();
+    if (!payload.text) delete payload.text;
+  }
+  if (typeof payload.source === 'string') {
+    payload.source = payload.source.trim() || undefined;
+  }
+  return Object.keys(payload).length > 0 ? payload : null;
+}
+
+export function resolveChatRequestOpeningMessage({
+  openingMessage = null,
+  openingPayload = null,
+  requestContext = null,
+} = {}) {
+  return normalizeText(
+    openingMessage,
+    normalizeText(openingPayload?.text, normalizeText(requestContext?.message, null)),
+  );
+}
+
+function resolveKickoffBriefSource({
+  kickoffBrief = null,
+  openingPayload = null,
+  requestContext = null,
+  source = null,
+} = {}) {
+  const normalizedContext = requestContext && typeof requestContext === 'object' && !Array.isArray(requestContext)
+    ? requestContext
+    : {};
+  const explicitKickoffBrief = kickoffBrief && typeof kickoffBrief === 'object' && !Array.isArray(kickoffBrief)
+    ? kickoffBrief
+    : null;
+  const contextKickoffBrief = normalizedContext.kickoffBrief && typeof normalizedContext.kickoffBrief === 'object' && !Array.isArray(normalizedContext.kickoffBrief)
+    ? normalizedContext.kickoffBrief
+    : null;
+  const fallbackSource = normalizeText(source, null) === 'world_broadcast'
+    ? 'world_broadcast_brief'
+    : 'chat_request_brief';
+  return normalizeText(
+    explicitKickoffBrief?.source,
+    normalizeText(
+      contextKickoffBrief?.source,
+      normalizeText(
+        openingPayload?.source,
+        normalizeText(normalizedContext.openingPayload?.source, fallbackSource),
+      ),
+    ),
+  );
+}
+
+function resolveChatRequestKickoffBrief({
+  kickoffBrief = null,
+  openingMessage = null,
+  openingPayload = null,
+  requestContext = null,
+  source = null,
+} = {}) {
+  const normalizedContext = requestContext && typeof requestContext === 'object' && !Array.isArray(requestContext)
+    ? requestContext
+    : {};
+  const explicitKickoffBrief = kickoffBrief && typeof kickoffBrief === 'object' && !Array.isArray(kickoffBrief)
+    ? kickoffBrief
+    : null;
+  const contextKickoffBrief = normalizedContext.kickoffBrief && typeof normalizedContext.kickoffBrief === 'object' && !Array.isArray(normalizedContext.kickoffBrief)
+    ? normalizedContext.kickoffBrief
+    : null;
+  const normalizedOpeningPayload = normalizeChatRequestOpeningPayload(
+    explicitKickoffBrief?.payload
+    ?? contextKickoffBrief?.payload
+    ?? openingPayload
+    ?? normalizedContext.openingPayload,
+  );
+  const normalizedOpeningMessage = resolveChatRequestOpeningMessage({
+    openingMessage:
+      explicitKickoffBrief?.text
+      ?? contextKickoffBrief?.text
+      ?? openingMessage,
+    openingPayload: normalizedOpeningPayload,
+    requestContext: normalizedContext,
+  });
+  return createKickoffBrief({
+    text: normalizedOpeningMessage,
+    payload: explicitKickoffBrief?.payload ?? contextKickoffBrief?.payload ?? normalizedOpeningPayload,
+    source: resolveKickoffBriefSource({
+      kickoffBrief: explicitKickoffBrief ?? contextKickoffBrief,
+      openingPayload: normalizedOpeningPayload,
+      requestContext: normalizedContext,
+      source,
+    }),
+  });
+}
+
+export function normalizeChatRequestInput({ requestContext = {}, source = null } = {}) {
+  const normalizedContext = requestContext && typeof requestContext === 'object' && !Array.isArray(requestContext)
+    ? requestContext
+    : {};
+  const conversationSource = normalizedContext.conversation && typeof normalizedContext.conversation === 'object' && !Array.isArray(normalizedContext.conversation)
+    ? normalizedContext.conversation
+    : {};
+  const conversation = normalizeChatRequestConversation({
+    ...conversationSource,
+    conversationKey: normalizedContext.conversationKey ?? conversationSource.conversationKey,
+    sessionKey: normalizedContext.sessionKey ?? conversationSource.sessionKey,
+  });
+  const kickoffBrief = resolveChatRequestKickoffBrief({
+    requestContext: normalizedContext,
+    source,
+  });
+  const openingPayload = normalizeChatRequestOpeningPayload(kickoffBrief?.payload ?? normalizedContext.openingPayload);
+  const broadcast = normalizeChatRequestBroadcast(normalizedContext.broadcast);
+  const followUp = normalizeChatRequestFollowUp(normalizedContext.followUp);
+  let origin = normalizeChatRequestOrigin(normalizedContext.origin, {
+    fallbackType: normalizeText(source, null) === 'world_broadcast' ? 'world_broadcast' : 'chat_request',
+  });
+
+  if (broadcast?.broadcastId && !origin?.broadcastId) {
+    origin = {
+      ...(origin || { type: normalizeText(source, null) === 'world_broadcast' ? 'world_broadcast' : 'chat_request' }),
+      broadcastId: broadcast.broadcastId,
+    };
+  }
+
+  return {
+    kickoffBrief,
+    openingMessage: resolveChatRequestOpeningMessage({
+      openingMessage: kickoffBrief?.text ?? null,
+      openingPayload: kickoffBrief?.payload ?? openingPayload,
+      requestContext: normalizedContext,
+    }),
+    openingPayload: kickoffBrief?.payload ?? openingPayload,
+    conversation,
+    origin,
+    broadcast,
+    followUp,
+  };
+}
+
+export function buildChatRequestContext({
+  kickoffBrief = null,
+  openingMessage = null,
+  openingPayload = null,
+  conversation = {},
+  origin = null,
+  broadcast = null,
+  followUp = null,
+  source = 'chat_request',
+} = {}) {
+  const normalizedConversation = normalizeChatRequestConversation(conversation);
+  const normalizedKickoffBrief = resolveChatRequestKickoffBrief({
+    kickoffBrief,
+    openingMessage,
+    openingPayload,
+    source,
+  });
+  const normalizedOpeningPayload = normalizeChatRequestOpeningPayload(
+    normalizedKickoffBrief?.payload ?? openingPayload,
+  );
+  const normalizedMessage = resolveChatRequestOpeningMessage({
+    openingMessage: normalizedKickoffBrief?.text ?? openingMessage,
+    openingPayload: normalizedOpeningPayload,
+  });
+  let normalizedOrigin = normalizeChatRequestOrigin(origin, {
+    fallbackType: normalizeText(source, null) === 'world_broadcast' ? 'world_broadcast' : 'chat_request',
+  });
+  let normalizedBroadcast = normalizeChatRequestBroadcast(broadcast);
+  const normalizedFollowUp = normalizeChatRequestFollowUp(followUp);
+
+  if (normalizedOrigin?.broadcastId && !normalizedBroadcast?.broadcastId) {
+    normalizedBroadcast = {
+      ...(normalizedBroadcast || {}),
+      broadcastId: normalizedOrigin.broadcastId,
+    };
+  }
+
+  const requestContext = {
+    type: 'chat_request',
+    ...(normalizedKickoffBrief ? { kickoffBrief: normalizedKickoffBrief } : {}),
+    ...(normalizedMessage ? { message: normalizedMessage } : {}),
+    ...(normalizedOpeningPayload ? { openingPayload: normalizedOpeningPayload } : {}),
+    ...(Object.keys(normalizedConversation).length > 0 ? { conversation: normalizedConversation } : {}),
+    ...(normalizedOrigin ? { origin: normalizedOrigin } : {}),
+    ...(normalizedBroadcast ? { broadcast: normalizedBroadcast } : {}),
+    ...(normalizedFollowUp ? { followUp: normalizedFollowUp } : {}),
+  };
+
+  return requestContext;
+}
+
+export function normalizeStoredChatRequest(input = {}, { defaultSource = 'chat_request' } = {}) {
+  const normalizedSource = normalizeText(input.source, defaultSource);
+  const normalizedRequest = normalizeChatRequestInput({
+    requestContext: input.requestContext,
+    source: normalizedSource,
+  });
+  const kickoffBrief = resolveChatRequestKickoffBrief({
+    kickoffBrief: input.kickoffBrief,
+    openingMessage: input.openingMessage,
+    openingPayload: input.openingPayload ?? normalizedRequest.openingPayload,
+    requestContext: input.requestContext,
+    source: normalizedSource,
+  });
+  const openingPayload = normalizeChatRequestOpeningPayload(
+    input.openingPayload ?? kickoffBrief?.payload ?? normalizedRequest.openingPayload,
+  );
+  const openingMessage = resolveChatRequestOpeningMessage({
+    openingMessage: kickoffBrief?.text ?? input.openingMessage,
+    openingPayload,
+    requestContext: input.requestContext,
+  });
+  const conversation = normalizeChatRequestConversation(
+    input.conversation && typeof input.conversation === 'object' && !Array.isArray(input.conversation)
+      ? input.conversation
+      : normalizedRequest.conversation,
+  );
+  const broadcast = normalizeChatRequestBroadcast(
+    input.broadcast && typeof input.broadcast === 'object' && !Array.isArray(input.broadcast)
+      ? input.broadcast
+      : normalizedRequest.broadcast,
+  );
+  const followUp = normalizeChatRequestFollowUp(
+    input.followUp && typeof input.followUp === 'object' && !Array.isArray(input.followUp)
+      ? input.followUp
+      : normalizedRequest.followUp,
+  );
+  let origin = normalizeChatRequestOrigin(
+    input.origin && typeof input.origin === 'object' && !Array.isArray(input.origin)
+      ? input.origin
+      : normalizedRequest.origin,
+    { fallbackType: normalizedSource === 'world_broadcast' ? 'world_broadcast' : 'chat_request' },
+  );
+
+  if (broadcast?.broadcastId && !origin?.broadcastId) {
+    origin = {
+      ...(origin || { type: normalizedSource === 'world_broadcast' ? 'world_broadcast' : 'chat_request' }),
+      broadcastId: broadcast.broadcastId,
+    };
+  }
+
+  const chatRequestId = normalizeText(input.chatRequestId, normalizeText(input.requestId, null));
+  const normalized = {
+    chatRequestId,
+    requestId: chatRequestId,
+    fromAgentId: normalizeText(input.fromAgentId, null),
+    toAgentId: normalizeText(input.toAgentId, null),
+    openingMessage,
+    ...(kickoffBrief ? { kickoffBrief } : {}),
+    ...(openingPayload ? { openingPayload } : {}),
+    conversation,
+    ...(origin ? { origin } : {}),
+    ...(broadcast ? { broadcast } : {}),
+    requestContext: buildChatRequestContext({
+      kickoffBrief,
+      openingMessage,
+      openingPayload,
+      conversation,
+      origin,
+      broadcast,
+      followUp,
+      source: normalizedSource,
+    }),
+    status: normalizeText(input.status, 'pending'),
+    createdAt: normalizeText(input.createdAt, null),
+    respondedAt: normalizeText(input.respondedAt, null),
+    expiresAt: normalizeText(input.expiresAt, null),
+    source: normalizedSource,
+  };
+
+  const acceptedByAgentId = normalizeText(input.acceptedByAgentId, null);
+  if (acceptedByAgentId) normalized.acceptedByAgentId = acceptedByAgentId;
+  const approvalGrantId = normalizeText(input.approvalGrantId, null);
+  if (approvalGrantId) normalized.approvalGrantId = approvalGrantId;
+  const kickoff = normalizeAcceptedChatKickoffRecord(cloneJsonObject(input.kickoff));
+  if (kickoff) normalized.kickoff = kickoff;
+
+  return normalized;
+}

package/src/lib/public-identity.js

@@ -0,0 +1,175 @@
+import { randomBytes } from 'crypto';
+
+export const PUBLIC_IDENTITY_STATUS = Object.freeze({
+  PENDING: 'pending',
+  READY: 'ready',
+});
+
+export const PUBLIC_IDENTITY_DISPLAY_NAME_MAX_LENGTH = 40;
+export const PUBLIC_IDENTITY_CODE_LENGTH = 6;
+const PUBLIC_IDENTITY_CODE_ALPHABET = '23456789ABCDEFGHJKLMNPQRSTUVWXYZ';
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function normalizeIsoTimestamp(value, fallback = null) {
+  const normalized = normalizeText(value, null);
+  if (!normalized) return fallback;
+  const timestamp = Date.parse(normalized);
+  return Number.isFinite(timestamp) ? new Date(timestamp).toISOString() : fallback;
+}
+
+function cloneObject(value, fallback = {}) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return { ...fallback };
+  return { ...value };
+}
+
+export function normalizePublicDisplayName(value, { fallback = null } = {}) {
+  const normalized = normalizeText(value, fallback);
+  if (!normalized) return fallback;
+  return normalized.slice(0, PUBLIC_IDENTITY_DISPLAY_NAME_MAX_LENGTH);
+}
+
+export function validatePublicDisplayName(value) {
+  const normalized = normalizeText(value, null);
+  if (!normalized) {
+    return {
+      ok: false,
+      code: 'display_name_required',
+      message: 'displayName is required',
+    };
+  }
+  if (normalized.length > PUBLIC_IDENTITY_DISPLAY_NAME_MAX_LENGTH) {
+    return {
+      ok: false,
+      code: 'display_name_too_long',
+      message: `displayName must be ${PUBLIC_IDENTITY_DISPLAY_NAME_MAX_LENGTH} characters or fewer`,
+    };
+  }
+  if (normalized.includes('#')) {
+    return {
+      ok: false,
+      code: 'display_name_reserved_character',
+      message: 'displayName must not include #',
+    };
+  }
+  if (/[\r\n\t]/.test(normalized)) {
+    return {
+      ok: false,
+      code: 'display_name_invalid_whitespace',
+      message: 'displayName must not include line breaks or tabs',
+    };
+  }
+  if (/[\u0000-\u001F\u007F]/.test(normalized)) {
+    return {
+      ok: false,
+      code: 'display_name_invalid_character',
+      message: 'displayName contains unsupported control characters',
+    };
+  }
+  return {
+    ok: true,
+    value: normalized,
+  };
+}
+
+export function generatePublicIdentityCode({ length = PUBLIC_IDENTITY_CODE_LENGTH } = {}) {
+  const targetLength = Number.isInteger(length) && length > 0 ? length : PUBLIC_IDENTITY_CODE_LENGTH;
+  const bytes = randomBytes(targetLength);
+  let output = '';
+  for (let index = 0; index < targetLength; index += 1) {
+    output += PUBLIC_IDENTITY_CODE_ALPHABET[bytes[index] % PUBLIC_IDENTITY_CODE_ALPHABET.length];
+  }
+  return output;
+}
+
+export function formatPublicIdentityDisplay({ displayName = null, code = null } = {}) {
+  const normalizedDisplayName = normalizeText(displayName, null);
+  const normalizedCode = normalizeText(code, null);
+  if (!normalizedDisplayName || !normalizedCode) return null;
+  return `${normalizedDisplayName}#${normalizedCode}`;
+}
+
+export function parsePublicIdentityDisplay(value) {
+  const normalized = normalizeText(value, null);
+  if (!normalized) return null;
+  const hashIndex = normalized.lastIndexOf('#');
+  if (hashIndex <= 0 || hashIndex >= normalized.length - 1) return null;
+  const displayName = normalizeText(normalized.slice(0, hashIndex), null);
+  const code = normalizeText(normalized.slice(hashIndex + 1), null)?.toUpperCase() || null;
+  if (!displayName || !code) return null;
+  if (displayName.includes('#')) return null;
+  return {
+    displayName,
+    code,
+    identity: `${displayName}#${code}`,
+  };
+}
+
+export function buildPublicIdentityRecord(input = {}, {
+  fallbackDisplayName = null,
+  statusFallback = PUBLIC_IDENTITY_STATUS.PENDING,
+  now = null,
+} = {}) {
+  const source = cloneObject(input);
+  const normalizedDisplayName = normalizePublicDisplayName(
+    source.displayName,
+    { fallback: normalizePublicDisplayName(fallbackDisplayName, { fallback: null }) },
+  );
+  const normalizedCode = normalizeText(source.code, null)?.toUpperCase() || null;
+  const normalizedStatus = normalizeText(source.status, null);
+  const resolvedStatus = normalizedStatus === PUBLIC_IDENTITY_STATUS.READY
+    ? PUBLIC_IDENTITY_STATUS.READY
+    : normalizedStatus === PUBLIC_IDENTITY_STATUS.PENDING
+      ? PUBLIC_IDENTITY_STATUS.PENDING
+      : (normalizedCode && normalizedDisplayName ? PUBLIC_IDENTITY_STATUS.READY : statusFallback);
+  const fallbackTimestamp = normalizeIsoTimestamp(now, null);
+  const confirmedAt = normalizeIsoTimestamp(source.confirmedAt, null)
+    || (resolvedStatus === PUBLIC_IDENTITY_STATUS.READY ? fallbackTimestamp : null);
+  const updatedAt = normalizeIsoTimestamp(source.updatedAt, fallbackTimestamp);
+  return {
+    displayName: normalizedDisplayName,
+    code: normalizedCode,
+    status: resolvedStatus,
+    confirmedAt,
+    updatedAt,
+  };
+}
+
+export function resolvePublicIdentity(agent = {}) {
+  const publicIdentity = buildPublicIdentityRecord(agent?.publicIdentity, {
+    fallbackDisplayName: agent?.displayName || agent?.agentId || null,
+    now: agent?.createdAt || null,
+  });
+  return {
+    ...publicIdentity,
+    displayIdentity: formatPublicIdentityDisplay(publicIdentity),
+  };
+}
+
+export function isPublicIdentityReady(agent = {}) {
+  return resolvePublicIdentity(agent).status === PUBLIC_IDENTITY_STATUS.READY;
+}
+
+export function buildPublicIdentityMissingFields(agent = {}) {
+  const publicIdentity = resolvePublicIdentity(agent);
+  const missingFields = [];
+  if (!publicIdentity.displayName) {
+    missingFields.push({
+      fieldId: 'displayName',
+      label: 'Public Name',
+      description: 'A public display name used in Claworld identity surfaces.',
+    });
+  }
+  if (!publicIdentity.code) {
+    missingFields.push({
+      fieldId: 'code',
+      label: 'Public Code',
+      description: 'A system-generated unique suffix used in the public identity.',
+    });
+  }
+  return missingFields;
+}