@xfxstudio/claworld 0.1.0

package/src/product-shell/contracts/chat-request-approval-policy.js

@@ -0,0 +1,98 @@
+const DEFAULT_MODE = 'manual_review';
+const SUPPORTED_MODES = Object.freeze([
+  DEFAULT_MODE,
+  'world_only',
+  'trusted_only',
+  'trusted_or_world',
+  'open',
+]);
+const SUPPORTED_ORIGIN_TYPES = Object.freeze([
+  'chat_request',
+  'world_broadcast',
+]);
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function normalizeToken(value, fallback = null) {
+  const normalized = normalizeText(value, fallback);
+  return normalized ? normalized.toLowerCase().replace(/[\s-]+/g, '_') : fallback;
+}
+
+function uniqueStrings(values = [], normalizer = (value) => normalizeText(value, null)) {
+  const seen = new Set();
+  const items = [];
+  for (const value of Array.isArray(values) ? values : []) {
+    const normalized = normalizer(value);
+    if (!normalized || seen.has(normalized)) continue;
+    seen.add(normalized);
+    items.push(normalized);
+  }
+  return items;
+}
+
+export const CHAT_REQUEST_APPROVAL_POLICY_SCHEMA_VERSION = 1;
+export const CHAT_REQUEST_APPROVAL_POLICY_MODES = SUPPORTED_MODES;
+export const CHAT_REQUEST_APPROVAL_POLICY_ORIGIN_TYPES = SUPPORTED_ORIGIN_TYPES;
+export const DEFAULT_CHAT_REQUEST_APPROVAL_POLICY_MODE = DEFAULT_MODE;
+
+export function normalizeChatRequestApprovalMode(value, fallback = DEFAULT_MODE) {
+  const normalized = normalizeToken(value, null);
+  switch (normalized) {
+    case 'manual':
+    case 'manual_review':
+    case 'review':
+      return DEFAULT_MODE;
+    case 'world':
+    case 'world_only':
+      return 'world_only';
+    case 'trusted':
+    case 'trusted_only':
+      return 'trusted_only';
+    case 'trusted_or_world':
+    case 'world_or_trusted':
+      return 'trusted_or_world';
+    case 'open':
+    case 'auto_accept':
+    case 'all':
+      return 'open';
+    default:
+      return SUPPORTED_MODES.includes(fallback) ? fallback : DEFAULT_MODE;
+  }
+}
+
+export function normalizeChatRequestApprovalOriginType(value, fallback = null) {
+  const normalized = normalizeToken(value, fallback);
+  return SUPPORTED_ORIGIN_TYPES.includes(normalized) ? normalized : fallback;
+}
+
+export function normalizeChatRequestApprovalBlocks(value = {}) {
+  const candidate = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  return {
+    originTypes: uniqueStrings(candidate.originTypes, (entry) => normalizeChatRequestApprovalOriginType(entry, null)).sort(),
+    worldIds: uniqueStrings(candidate.worldIds, (entry) => normalizeText(entry, null)).sort(),
+  };
+}
+
+export function normalizeChatRequestApprovalPolicy(
+  value = {},
+  { fallbackMode = DEFAULT_MODE, legacyAutoAccept = null } = {},
+) {
+  const candidate = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  const normalizedLegacyAutoAccept = typeof legacyAutoAccept === 'boolean' ? legacyAutoAccept : null;
+  const mode = normalizeText(candidate.mode, null)
+    ? normalizeChatRequestApprovalMode(candidate.mode, fallbackMode)
+    : normalizedLegacyAutoAccept === true
+      ? 'open'
+      : normalizedLegacyAutoAccept === false
+        ? DEFAULT_MODE
+        : normalizeChatRequestApprovalMode(fallbackMode, DEFAULT_MODE);
+
+  return {
+    mode,
+    blocks: normalizeChatRequestApprovalBlocks(candidate.blocks),
+  };
+}

package/src/product-shell/contracts/world-manifest.js

@@ -0,0 +1,435 @@
+import { projectCandidateFeedModel } from './candidate-feed.js';
+import { buildWorldSessionStartupText } from './world-orchestration.js';
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function normalizeStringList(values = []) {
+  if (!Array.isArray(values)) return [];
+  return [...new Set(values.map((value) => normalizeText(value, null)).filter(Boolean))];
+}
+
+function normalizeWorldEligibility(value, fallback = 'active') {
+  const normalized = normalizeText(value, fallback);
+  if (normalized === 'joined') return 'joined';
+  return 'active';
+}
+
+function normalizeBroadcastAudience(value, fallback = 'members') {
+  const normalized = normalizeText(value, fallback);
+  if (normalized === 'admins') return 'admins';
+  if (normalized === 'admins_and_owner') return 'admins_and_owner';
+  return 'members';
+}
+
+function normalizeBroadcastReplyPolicy(value, fallback = 'zero') {
+  const normalized = normalizeText(value, fallback);
+  if (normalized === 'at_most_one') return 'at_most_one';
+  return 'zero';
+}
+
+function normalizeBroadcastConfig(broadcast = {}, { enabled = false } = {}) {
+  const normalized = broadcast && typeof broadcast === 'object' && !Array.isArray(broadcast)
+    ? broadcast
+    : {};
+
+  return {
+    enabled: normalized.enabled === true || enabled === true,
+    audience: normalizeBroadcastAudience(normalized.audience, 'members'),
+    replyPolicy: normalizeBroadcastReplyPolicy(normalized.replyPolicy, 'zero'),
+    excludeSelf: normalized.excludeSelf !== false,
+  };
+}
+
+function normalizeField(field = {}, index = 0, { required = false } = {}) {
+  const fieldId = normalizeText(field.fieldId || field.id, `field_${index + 1}`);
+  return {
+    fieldId,
+    label: normalizeText(field.label, fieldId),
+    type: normalizeText(field.type, 'string'),
+    source: normalizeText(field.source, 'profile'),
+    required: field.required === true || required,
+    description: normalizeText(field.description, null),
+    examples: normalizeStringList(field.examples),
+    constraints: field.constraints && typeof field.constraints === 'object' ? field.constraints : {},
+  };
+}
+
+function normalizeRole(role = {}, index = 0) {
+  const roleId = normalizeText(role.roleId || role.id, `role_${index + 1}`);
+  return {
+    roleId,
+    label: normalizeText(role.label, roleId),
+    objective: normalizeText(role.objective, null),
+    promptSummary: normalizeText(role.promptSummary, null),
+  };
+}
+
+function normalizeExampleSignals(exampleSignals = {}) {
+  const normalizeGroup = (key) => (Array.isArray(exampleSignals[key]) ? exampleSignals[key] : []);
+  return {
+    intentSignals: normalizeGroup('intentSignals'),
+    conversationSignals: normalizeGroup('conversationSignals'),
+    agentSignals: normalizeGroup('agentSignals'),
+  };
+}
+
+function normalizeJoinSchema(joinSchema = {}) {
+  const requiredFields = Array.isArray(joinSchema.requiredFields)
+    ? joinSchema.requiredFields.map((field, index) => normalizeField(field, index, { required: true }))
+    : [];
+  const optionalFields = Array.isArray(joinSchema.optionalFields)
+    ? joinSchema.optionalFields.map((field, index) => normalizeField(field, index, { required: false }))
+    : [];
+
+  return {
+    requiredFields,
+    optionalFields,
+    hints: normalizeStringList(joinSchema.hints),
+  };
+}
+
+function normalizeSearchSchema(searchSchema = {}, joinSchema = {}) {
+  const fieldLookup = new Map(
+    [...joinSchema.requiredFields, ...joinSchema.optionalFields].map((field) => [field.fieldId, field]),
+  );
+  const rawInputFieldIds = Array.isArray(searchSchema.inputFieldIds)
+    ? searchSchema.inputFieldIds
+    : (Array.isArray(searchSchema.inputFields)
+      ? searchSchema.inputFields.map((field) => (typeof field === 'string' ? field : field.fieldId || field.id))
+      : joinSchema.requiredFields.map((field) => field.fieldId));
+  const inputFieldIds = normalizeStringList(rawInputFieldIds);
+  const inputFields = inputFieldIds.map((fieldId, index) => {
+    const referenced = fieldLookup.get(fieldId);
+    if (referenced) return { ...referenced };
+    return normalizeField({ fieldId, label: fieldId }, index, { required: false });
+  });
+
+  return {
+    mode: normalizeText(searchSchema.mode, 'membership_profile_search'),
+    inputFieldIds,
+    inputFields,
+    resultFields: normalizeStringList(
+      searchSchema.resultFields || [
+        'agentId',
+        'playerId',
+        'membershipId',
+        'worldId',
+        'displayName',
+        'headline',
+        'address',
+        'online',
+        'matchedFieldIds',
+        'score',
+        'profileSummary',
+      ],
+    ),
+    onlineOnly: searchSchema.onlineOnly !== false,
+    defaultLimit: Number.isFinite(Number(searchSchema.defaultLimit))
+      ? Math.max(1, Math.trunc(Number(searchSchema.defaultLimit)))
+      : 10,
+    summary: normalizeText(
+      searchSchema.summary,
+      'Search active online world members by world-profile overlap before opening a conversation.',
+    ),
+    hints: normalizeStringList(searchSchema.hints),
+  };
+}
+
+export function normalizeWorldManifest(manifest = {}, index = 0) {
+  const worldId = normalizeText(manifest.worldId || manifest.id, `world_${index + 1}`);
+  const joinSchema = normalizeJoinSchema(manifest.joinSchema);
+  const searchSchema = normalizeSearchSchema(manifest.searchSchema, joinSchema);
+  const defaultInteractionRules = normalizeText(manifest.sessionTemplate?.worldRules?.openingText, null);
+  const defaultProhibitedRules = normalizeText(manifest.sessionTemplate?.raiseHandPolicy?.summary, null);
+
+  return {
+    worldId,
+    slug: normalizeText(manifest.slug, worldId),
+    displayName: normalizeText(manifest.displayName, worldId),
+    summary: normalizeText(manifest.summary, null),
+    description: normalizeText(manifest.description, normalizeText(manifest.summary, null)),
+    category: normalizeText(manifest.category, 'general'),
+    lifecycle: normalizeText(manifest.lifecycle, 'scaffold'),
+    tags: normalizeStringList(manifest.tags),
+    interactionRules: normalizeText(manifest.interactionRules, defaultInteractionRules),
+    prohibitedRules: normalizeText(manifest.prohibitedRules, defaultProhibitedRules),
+    ratingRules: normalizeText(
+      manifest.ratingRules,
+      'After the interaction ends, each agent should rate the other participant from 1 to 10 based on fit, clarity, and rule compliance.',
+    ),
+    creatorAgentId: normalizeText(manifest.creatorAgentId, null),
+    adminAgentIds: normalizeStringList(manifest.adminAgentIds),
+    eligibility: normalizeWorldEligibility(manifest.eligibility, 'active'),
+    broadcast: normalizeBroadcastConfig(manifest.broadcast, {
+      enabled: manifest.broadcast?.enabled === true,
+    }),
+    status: normalizeText(manifest.status, manifest.enabled === true ? 'enabled' : 'draft'),
+    enabled: manifest.enabled === true,
+    schemaVersion: Number.isFinite(Number(manifest.schemaVersion)) ? Math.max(1, Math.trunc(Number(manifest.schemaVersion))) : 1,
+    createdAt: normalizeText(manifest.createdAt, null),
+    updatedAt: normalizeText(manifest.updatedAt, null),
+    metrics: manifest.metrics && typeof manifest.metrics === 'object'
+      ? {
+        totalConversationCount: Number.isFinite(Number(manifest.metrics.totalConversationCount))
+          ? Math.max(0, Math.trunc(Number(manifest.metrics.totalConversationCount)))
+          : 0,
+      }
+      : { totalConversationCount: 0 },
+    roles: Array.isArray(manifest.roles)
+      ? manifest.roles.map((role, roleIndex) => normalizeRole(role, roleIndex))
+      : [],
+    joinSchema,
+    searchSchema,
+    matching: {
+      mode: normalizeText(manifest.matching?.mode, 'manual_review'),
+      cadence: normalizeText(manifest.matching?.cadence, 'on_demand'),
+      strategySummary: normalizeText(manifest.matching?.strategySummary, null),
+      candidateSources: normalizeStringList(manifest.matching?.candidateSources),
+    },
+    sessionTemplate: {
+      mode: normalizeText(manifest.sessionTemplate?.mode, 'a2a'),
+      maxTurns: Number.isFinite(Number(manifest.sessionTemplate?.maxTurns))
+        ? Math.max(1, Number(manifest.sessionTemplate.maxTurns))
+        : 6,
+      turnTimeoutMs: Number.isFinite(Number(manifest.sessionTemplate?.turnTimeoutMs))
+        ? Math.max(1000, Number(manifest.sessionTemplate.turnTimeoutMs))
+        : 60_000,
+      raiseHandPolicy: {
+        mode: normalizeText(manifest.sessionTemplate?.raiseHandPolicy?.mode, 'dual_raise_hand'),
+        summary: normalizeText(manifest.sessionTemplate?.raiseHandPolicy?.summary, null),
+      },
+      worldRules: {
+        openingText: normalizeText(manifest.sessionTemplate?.worldRules?.openingText, null),
+        turnMessageRules: Array.isArray(manifest.sessionTemplate?.worldRules?.turnMessageRules)
+          ? manifest.sessionTemplate.worldRules.turnMessageRules
+          : [],
+        convergence: manifest.sessionTemplate?.worldRules?.convergence || {},
+        stateChangeMessages: manifest.sessionTemplate?.worldRules?.stateChangeMessages || {},
+      },
+    },
+    resultContract: {
+      schemaId: normalizeText(manifest.resultContract?.schemaId, `${worldId}.result.v1`),
+      outputs: normalizeStringList(manifest.resultContract?.outputs),
+      successCriteria: normalizeStringList(manifest.resultContract?.successCriteria),
+      exampleSignals: normalizeExampleSignals(manifest.resultContract?.exampleSignals),
+    },
+    meta: {
+      status: normalizeText(manifest.meta?.status, 'scaffold_ready'),
+      persistence: normalizeText(manifest.meta?.persistence, 'in_memory_catalog'),
+    },
+  };
+}
+
+export function projectWorldCard(world) {
+  const agentSummary = {
+    displayName: world.displayName,
+    summary: world.summary,
+    category: world.category,
+    requiredFieldCount: world.joinSchema.requiredFields.length,
+    matchingMode: world.matching.mode,
+    sessionMode: world.sessionTemplate.mode,
+  };
+
+  return {
+    worldId: world.worldId,
+    slug: world.slug,
+    displayName: agentSummary.displayName,
+    summary: agentSummary.summary,
+    category: agentSummary.category,
+    lifecycle: world.lifecycle,
+    tags: world.tags,
+    requiredFieldCount: agentSummary.requiredFieldCount,
+    roleCount: world.roles.length,
+    matchingMode: agentSummary.matchingMode,
+    sessionMode: agentSummary.sessionMode,
+    createdAt: world.createdAt || null,
+    updatedAt: world.updatedAt || null,
+    status: world.meta.status,
+    agentSummary,
+  };
+}
+
+export function projectJoinPlan(world) {
+  return {
+    worldId: world.worldId,
+    requiredFields: world.joinSchema.requiredFields,
+    optionalFields: world.joinSchema.optionalFields,
+    hints: world.joinSchema.hints,
+    nextAction: 'collect_profile_fields_then_call_join',
+  };
+}
+
+function projectFieldGuide(fields = [], { required = false } = {}) {
+  return fields.map((field) => ({
+    fieldId: field.fieldId,
+    label: field.label,
+    required,
+    type: field.type,
+    source: field.source,
+    description: field.description,
+    examples: field.examples,
+    constraints: field.constraints,
+  }));
+}
+
+export function projectSearchModel(world) {
+  return {
+    modelId: `${world.worldId}.search.v1`,
+    worldId: world.worldId,
+    mode: world.searchSchema.mode,
+    previewRoute: `/v1/worlds/${world.worldId}/search`,
+    inputFieldIds: world.searchSchema.inputFieldIds,
+    inputFields: projectFieldGuide(world.searchSchema.inputFields, { required: false }),
+    resultFields: world.searchSchema.resultFields,
+    viewerRequirement: 'active_membership',
+    onlineOnly: world.searchSchema.onlineOnly,
+    defaultLimit: world.searchSchema.defaultLimit,
+    summary: world.searchSchema.summary,
+    hints: world.searchSchema.hints,
+    status: 'phase1_world_search',
+  };
+}
+
+export function projectWorldDetail(world) {
+  const joinPlan = projectJoinPlan(world);
+  const requiredFieldGuide = projectFieldGuide(world.joinSchema.requiredFields, { required: true });
+  const optionalFieldGuide = projectFieldGuide(world.joinSchema.optionalFields, { required: false });
+  const allFieldGuide = [...requiredFieldGuide, ...optionalFieldGuide];
+  const candidateFeedOverview = projectCandidateFeedModel(world);
+  const searchSchema = projectSearchModel(world);
+  const runtimeStartupContext = {
+    worldId: world.worldId,
+    status: 'ready',
+    source: 'product_shell_session_startup',
+    text: buildWorldSessionStartupText({
+      worldId: world.worldId,
+      displayName: world.displayName,
+      summary: world.summary,
+      interactionRules: world.interactionRules,
+      prohibitedRules: world.prohibitedRules,
+      ratingRules: world.ratingRules,
+      sessionMode: world.sessionTemplate.mode,
+      sessionOverview: {
+        worldId: world.worldId,
+        mode: world.sessionTemplate.mode,
+        maxTurns: world.sessionTemplate.maxTurns,
+        turnTimeoutMs: world.sessionTemplate.turnTimeoutMs,
+        raiseHandPolicy: world.sessionTemplate.raiseHandPolicy,
+        openingText: world.sessionTemplate.worldRules.openingText,
+        convergence: world.sessionTemplate.worldRules.convergence,
+      },
+    }),
+  };
+
+  return {
+    world: world,
+    agentSummary: {
+      displayName: world.displayName,
+      summary: world.summary,
+      category: world.category,
+      requiredFieldCount: world.joinSchema.requiredFields.length,
+      optionalFieldCount: world.joinSchema.optionalFields.length,
+      matchingMode: world.matching.mode,
+      sessionMode: world.sessionTemplate.mode,
+    },
+    joinSchema: {
+      worldId: world.worldId,
+      requiredFields: world.joinSchema.requiredFields,
+      optionalFields: world.joinSchema.optionalFields,
+      requiredFieldIds: requiredFieldGuide.map((field) => field.fieldId),
+      optionalFieldIds: optionalFieldGuide.map((field) => field.fieldId),
+      requiredFieldCount: requiredFieldGuide.length,
+      optionalFieldCount: optionalFieldGuide.length,
+      hints: world.joinSchema.hints,
+      nextAction: joinPlan.nextAction,
+    },
+    fieldGuide: {
+      required: requiredFieldGuide,
+      optional: optionalFieldGuide,
+      allFields: allFieldGuide,
+    },
+    sessionOverview: {
+      worldId: world.worldId,
+      mode: world.sessionTemplate.mode,
+      maxTurns: world.sessionTemplate.maxTurns,
+      turnTimeoutMs: world.sessionTemplate.turnTimeoutMs,
+      raiseHandPolicy: world.sessionTemplate.raiseHandPolicy,
+      openingText: world.sessionTemplate.worldRules.openingText,
+      convergence: world.sessionTemplate.worldRules.convergence,
+      turnMessageRules: world.sessionTemplate.worldRules.turnMessageRules,
+      expectationSummary:
+        `Expect a ${world.sessionTemplate.mode} session with up to ${world.sessionTemplate.maxTurns} turns and ` +
+        `a ${world.sessionTemplate.turnTimeoutMs}ms turn timeout before the world asks both agents to converge.`,
+      status: 'scaffold_ready',
+    },
+    matchingOverview: {
+      worldId: world.worldId,
+      mode: world.matching.mode,
+      cadence: world.matching.cadence,
+      strategySummary: world.matching.strategySummary,
+      candidateSources: world.matching.candidateSources,
+      inputFields: requiredFieldGuide.map((field) => field.fieldId),
+      optionalContextFields: optionalFieldGuide.map((field) => field.fieldId),
+      searchMode: searchSchema.mode,
+      deliveryMode: candidateFeedOverview.deliveryMode,
+      status: 'scaffold_ready',
+    },
+    searchSchema,
+    candidateFeedOverview,
+    joinPlan,
+    runtimeStartupContext,
+  };
+}
+
+export function projectSessionStartupContext(world) {
+  const runtimeStartupContext = {
+    worldId: world.worldId,
+    status: 'ready',
+    source: 'product_shell_session_startup',
+    text: buildWorldSessionStartupText({
+      worldId: world.worldId,
+      displayName: world.displayName,
+      summary: world.summary,
+      interactionRules: world.interactionRules,
+      prohibitedRules: world.prohibitedRules,
+      ratingRules: world.ratingRules,
+      sessionMode: world.sessionTemplate.mode,
+      sessionOverview: {
+        worldId: world.worldId,
+        mode: world.sessionTemplate.mode,
+        maxTurns: world.sessionTemplate.maxTurns,
+        turnTimeoutMs: world.sessionTemplate.turnTimeoutMs,
+        raiseHandPolicy: world.sessionTemplate.raiseHandPolicy,
+        openingText: world.sessionTemplate.worldRules.openingText,
+        convergence: world.sessionTemplate.worldRules.convergence,
+      },
+    }),
+  };
+
+  return {
+    worldId: world.worldId,
+    displayName: world.displayName,
+    summary: world.summary,
+    interactionRules: world.interactionRules,
+    prohibitedRules: world.prohibitedRules,
+    ratingRules: world.ratingRules,
+    sessionMode: world.sessionTemplate.mode,
+    sessionOverview: {
+      worldId: world.worldId,
+      mode: world.sessionTemplate.mode,
+      maxTurns: world.sessionTemplate.maxTurns,
+      turnTimeoutMs: world.sessionTemplate.turnTimeoutMs,
+      raiseHandPolicy: world.sessionTemplate.raiseHandPolicy,
+      openingText: world.sessionTemplate.worldRules.openingText,
+      convergence: world.sessionTemplate.worldRules.convergence,
+      turnMessageRules: world.sessionTemplate.worldRules.turnMessageRules,
+    },
+    status: 'ready',
+    source: 'product_shell_session_startup',
+    runtimeStartupContext,
+  };
+}