@xfxstudio/claworld 0.1.0

package/src/openclaw/runtime/product-shell-helper.js

@@ -0,0 +1,1712 @@
+import { resolveClaworldRuntimeConfig } from '../plugin/config-schema.js';
+import { buildRuntimeAuthHeaders } from '../plugin/account-identity.js';
+import { createRuntimeBoundaryError } from '../../lib/runtime-errors.js';
+import {
+  buildCandidateDeliverySummary as buildBackendCandidateDeliverySummary,
+  buildWorldJoinOutcomeOrchestration as buildBackendWorldJoinOutcomeOrchestration,
+  buildRequiredFieldExplanation as buildBackendRequiredFieldExplanation,
+  buildWorldProfileCollectionFlow as buildBackendWorldProfileCollectionFlow,
+  buildWorldSelectionPrompt as buildBackendWorldSelectionPrompt,
+  resolveWorldSelection as resolveBackendWorldSelection,
+} from '../../product-shell/contracts/world-orchestration.js';
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function normalizeInteger(value, fallback = 0) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(0, Math.trunc(parsed));
+}
+
+function normalizeStringList(values = []) {
+  if (!Array.isArray(values)) return [];
+  return [...new Set(values.map((value) => normalizeText(value, null)).filter(Boolean))];
+}
+
+function normalizeBroadcastConfig(broadcast = {}) {
+  return {
+    enabled: broadcast.enabled === true,
+    audience: normalizeText(broadcast.audience, 'members'),
+    replyPolicy: normalizeText(broadcast.replyPolicy, 'zero'),
+    excludeSelf: broadcast.excludeSelf !== false,
+  };
+}
+
+function isEmptyProfileValue(value) {
+  if (value == null) return true;
+  if (typeof value === 'string') return value.trim() === '';
+  if (Array.isArray(value)) return value.length === 0 || value.every((entry) => isEmptyProfileValue(entry));
+  if (typeof value === 'object') {
+    const entries = Object.values(value);
+    return entries.length === 0 || entries.every((entry) => isEmptyProfileValue(entry));
+  }
+  return false;
+}
+
+function normalizeProfileValue(value) {
+  if (typeof value === 'string') return value.trim();
+  if (Array.isArray(value)) {
+    return value
+      .map((entry) => normalizeProfileValue(entry))
+      .filter((entry) => entry !== undefined && !isEmptyProfileValue(entry));
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value)
+        .filter(([, entry]) => entry !== undefined)
+        .map(([key, entry]) => [key, normalizeProfileValue(entry)]),
+    );
+  }
+  return value;
+}
+
+function normalizeProfile(profile = {}) {
+  if (!profile || typeof profile !== 'object' || Array.isArray(profile)) return {};
+
+  return Object.fromEntries(
+    Object.entries(profile)
+      .filter(([key, value]) => normalizeText(key, null) && value !== undefined)
+      .map(([key, value]) => [normalizeText(key, null), normalizeProfileValue(value)]),
+  );
+}
+
+function mergeProfileState(profile = {}, profileUpdate = {}) {
+  return {
+    ...normalizeProfile(profile),
+    ...normalizeProfile(profileUpdate),
+  };
+}
+
+function normalizeLookupText(value) {
+  return normalizeText(value, '')?.toLowerCase() || '';
+}
+
+function sentenceCase(value, fallback = '') {
+  const normalized = normalizeText(value, fallback);
+  if (!normalized) return fallback;
+  return /[.!?]$/.test(normalized) ? normalized : `${normalized}.`;
+}
+
+function quoteExample(example) {
+  return `"${String(example).trim()}"`;
+}
+
+function joinAsNaturalLanguage(values = []) {
+  const items = values.filter(Boolean);
+  if (items.length === 0) return '';
+  if (items.length === 1) return items[0];
+  if (items.length === 2) return `${items[0]} and ${items[1]}`;
+  return `${items.slice(0, -1).join(', ')}, and ${items.at(-1)}`;
+}
+
+function summarizeWorldChoices(items = []) {
+  return items.map((world) => `${world.displayName} [${world.worldId}]`);
+}
+
+function normalizeWorldSummary(world = {}) {
+  const summary = world.agentSummary && typeof world.agentSummary === 'object' ? world.agentSummary : world;
+  const rawWorldId = world.worldId || summary.worldId;
+
+  return {
+    worldId: normalizeText(rawWorldId, 'unknown-world'),
+    displayName: normalizeText(summary.displayName || world.displayName, normalizeText(rawWorldId, 'Unknown World')),
+    summary: normalizeText(summary.summary || world.summary, ''),
+    category: normalizeText(summary.category || world.category, 'general'),
+    hotness: normalizeInteger(summary.hotness || world.hotness || world.activatedMemberCount, 0),
+    requiredFieldCount: normalizeInteger(summary.requiredFieldCount || world.requiredFieldCount, 0),
+    matchingMode: normalizeText(summary.matchingMode || world.matchingMode, 'manual_review'),
+    sessionMode: normalizeText(summary.sessionMode || world.sessionMode, 'a2a'),
+  };
+}
+
+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 normalizeSearchSchema(payload = {}, { worldId = null, fallbackFields = [] } = {}) {
+  const rawInputFields = Array.isArray(payload.inputFields) && payload.inputFields.length > 0
+    ? payload.inputFields
+    : fallbackFields;
+  const inputFields = rawInputFields.map((field, index) => normalizeField(field, index, { required: false }));
+  const inputFieldIds = normalizeStringList(
+    Array.isArray(payload.inputFieldIds)
+      ? payload.inputFieldIds
+      : inputFields.map((field) => field.fieldId),
+  );
+
+  return {
+    modelId: normalizeText(payload.modelId, worldId ? `${worldId}.search.v1` : 'world.search.v1'),
+    worldId: normalizeText(payload.worldId, worldId || 'unknown-world'),
+    mode: normalizeText(payload.mode, 'membership_profile_search'),
+    previewRoute: normalizeText(payload.previewRoute, worldId ? `/v1/worlds/${worldId}/search` : '/v1/worlds/:worldId/search'),
+    inputFieldIds,
+    inputFields,
+    resultFields: normalizeStringList(payload.resultFields),
+    viewerRequirement: normalizeText(payload.viewerRequirement, 'active_membership'),
+    onlineOnly: payload.onlineOnly !== false,
+    defaultLimit: normalizeInteger(payload.defaultLimit, 10),
+    summary: normalizeText(payload.summary, ''),
+    hints: normalizeStringList(payload.hints),
+    status: normalizeText(payload.status, 'phase1_world_search'),
+  };
+}
+
+function normalizeWorldDetail(payload = {}) {
+  if (Array.isArray(payload.requiredFields) || Array.isArray(payload.optionalFields)) {
+    const requiredFields = Array.isArray(payload.requiredFields)
+      ? payload.requiredFields.map((field, index) => normalizeField(field, index, { required: true }))
+      : [];
+    const optionalFields = Array.isArray(payload.optionalFields)
+      ? payload.optionalFields.map((field, index) => normalizeField(field, index, { required: false }))
+      : [];
+    const normalizedWorldId = normalizeText(payload.worldId, 'unknown-world');
+
+    return {
+      status: normalizeText(payload.status, 'ready'),
+      source: normalizeText(payload.source, 'product_shell'),
+      worldId: normalizedWorldId,
+      displayName: normalizeText(payload.displayName, normalizedWorldId),
+      summary: normalizeText(payload.summary, ''),
+      description: normalizeText(payload.description, normalizeText(payload.summary, '')),
+      category: normalizeText(payload.category, 'general'),
+      requiredFieldCount: normalizeInteger(payload.requiredFieldCount, requiredFields.length) || requiredFields.length,
+      optionalFieldCount: normalizeInteger(payload.optionalFieldCount, optionalFields.length) || optionalFields.length,
+      matchingMode: normalizeText(payload.matchingMode, 'manual_review'),
+      sessionMode: normalizeText(payload.sessionMode, 'a2a'),
+      interactionRules: normalizeText(payload.interactionRules, null),
+      prohibitedRules: normalizeText(payload.prohibitedRules, null),
+      ratingRules: normalizeText(payload.ratingRules, null),
+      adminAgentIds: normalizeStringList(payload.adminAgentIds),
+      eligibility: normalizeText(payload.eligibility, 'active'),
+      broadcast: normalizeBroadcastConfig(payload.broadcast),
+      requiredFields,
+      optionalFields,
+      hints: normalizeStringList(payload.hints),
+      nextAction: normalizeText(payload.nextAction, 'collect_profile_fields_then_call_join'),
+      sessionOverview: payload.sessionOverview && typeof payload.sessionOverview === 'object' ? payload.sessionOverview : {},
+      matchingOverview: payload.matchingOverview && typeof payload.matchingOverview === 'object' ? payload.matchingOverview : {},
+      requiredFieldExplanation:
+        payload.requiredFieldExplanation && typeof payload.requiredFieldExplanation === 'object'
+          ? payload.requiredFieldExplanation
+          : null,
+      runtimeStartupContext:
+        payload.runtimeStartupContext && typeof payload.runtimeStartupContext === 'object'
+          ? payload.runtimeStartupContext
+          : null,
+      searchSchema: normalizeSearchSchema(payload.searchSchema || {}, {
+        worldId: normalizedWorldId,
+        fallbackFields: requiredFields,
+      }),
+    };
+  }
+
+  const world = payload.world && typeof payload.world === 'object' ? payload.world : {};
+  const agentSummary = payload.agentSummary && typeof payload.agentSummary === 'object' ? payload.agentSummary : {};
+  const joinSchema = payload.joinSchema && typeof payload.joinSchema === 'object' ? payload.joinSchema : {};
+  const fieldGuide = payload.fieldGuide && typeof payload.fieldGuide === 'object' ? payload.fieldGuide : {};
+  const sessionOverview = payload.sessionOverview && typeof payload.sessionOverview === 'object'
+    ? payload.sessionOverview
+    : {};
+  const matchingOverview = payload.matchingOverview && typeof payload.matchingOverview === 'object'
+    ? payload.matchingOverview
+    : {};
+  const searchOverview = payload.searchSchema && typeof payload.searchSchema === 'object'
+    ? payload.searchSchema
+    : {};
+
+  const requiredInput = Array.isArray(fieldGuide.required) && fieldGuide.required.length > 0
+    ? fieldGuide.required
+    : (Array.isArray(joinSchema.requiredFields) ? joinSchema.requiredFields : []);
+  const optionalInput = Array.isArray(fieldGuide.optional) && fieldGuide.optional.length > 0
+    ? fieldGuide.optional
+    : (Array.isArray(joinSchema.optionalFields) ? joinSchema.optionalFields : []);
+
+  const requiredFields = requiredInput.map((field, index) => normalizeField(field, index, { required: true }));
+  const optionalFields = optionalInput.map((field, index) => normalizeField(field, index, { required: false }));
+  const worldId = normalizeText(world.worldId || joinSchema.worldId, 'unknown-world');
+  const displayName = normalizeText(agentSummary.displayName || world.displayName, worldId);
+
+  return {
+    status: 'ready',
+    source: 'product_shell',
+    worldId,
+    displayName,
+    summary: normalizeText(agentSummary.summary || world.summary, ''),
+    description: normalizeText(world.description, normalizeText(agentSummary.summary || world.summary, '')),
+    category: normalizeText(agentSummary.category || world.category, 'general'),
+    requiredFieldCount: normalizeInteger(joinSchema.requiredFieldCount, requiredFields.length) || requiredFields.length,
+    optionalFieldCount: normalizeInteger(joinSchema.optionalFieldCount, optionalFields.length) || optionalFields.length,
+    matchingMode: normalizeText(agentSummary.matchingMode || matchingOverview.mode || world.matching?.mode, 'manual_review'),
+    sessionMode: normalizeText(agentSummary.sessionMode || sessionOverview.mode || world.sessionTemplate?.mode, 'a2a'),
+    interactionRules: normalizeText(world.interactionRules, null),
+    prohibitedRules: normalizeText(world.prohibitedRules, null),
+    ratingRules: normalizeText(world.ratingRules, null),
+    adminAgentIds: normalizeStringList(world.adminAgentIds),
+    eligibility: normalizeText(world.eligibility, 'active'),
+    broadcast: normalizeBroadcastConfig(world.broadcast),
+    requiredFields,
+    optionalFields,
+    hints: normalizeStringList(joinSchema.hints),
+    nextAction: normalizeText(joinSchema.nextAction, 'collect_profile_fields_then_call_join'),
+    sessionOverview,
+    matchingOverview,
+    requiredFieldExplanation:
+      payload.requiredFieldExplanation && typeof payload.requiredFieldExplanation === 'object'
+        ? payload.requiredFieldExplanation
+        : null,
+    runtimeStartupContext:
+      payload.runtimeStartupContext && typeof payload.runtimeStartupContext === 'object'
+        ? payload.runtimeStartupContext
+        : null,
+    searchSchema: normalizeSearchSchema(searchOverview, {
+      worldId,
+      fallbackFields: [...requiredFields, ...optionalFields],
+    }),
+  };
+}
+
+function normalizeJoinCheckField(field = {}, index = 0) {
+  return normalizeField(field, index, { required: true });
+}
+
+function normalizeJoinCheckResponse(payload = {}, { worldId = null, profile = {} } = {}) {
+  const missingFields = Array.isArray(payload.missingFields)
+    ? payload.missingFields.map((field, index) => normalizeJoinCheckField(field, index))
+    : [];
+  const guidance = payload.missingFieldGuidance && typeof payload.missingFieldGuidance === 'object'
+    ? payload.missingFieldGuidance
+    : {};
+  const orderedMissingFields = Array.isArray(guidance.orderedMissingFields)
+    ? guidance.orderedMissingFields.map((field, index) => normalizeJoinCheckField(field, index))
+    : missingFields;
+  const fallbackNextMissingField = orderedMissingFields[0] || missingFields[0] || null;
+  const nextMissingField = payload.nextMissingField
+    ? normalizeJoinCheckField(payload.nextMissingField)
+    : (guidance.nextMissingField ? normalizeJoinCheckField(guidance.nextMissingField) : fallbackNextMissingField);
+  const accepted = payload.accepted === true || orderedMissingFields.length === 0;
+
+  return {
+    worldId: normalizeText(payload.worldId, worldId || 'unknown-world'),
+    accepted,
+    status: normalizeText(payload.status, accepted ? 'eligible' : 'needs_profile'),
+    missingFields,
+    nextMissingField,
+    missingFieldGuidance: {
+      mode: normalizeText(guidance.mode, nextMissingField ? 'ordered_required_fields' : 'complete'),
+      orderedMissingFields,
+      orderedMissingFieldIds: normalizeStringList(
+        Array.isArray(guidance.orderedMissingFieldIds)
+          ? guidance.orderedMissingFieldIds
+          : orderedMissingFields.map((field) => field.fieldId),
+      ),
+      nextMissingField,
+      remainingRequiredFieldCount: normalizeInteger(guidance.remainingRequiredFieldCount, orderedMissingFields.length),
+    },
+    normalizedProfile: normalizeProfile(
+      payload.normalizedProfile && typeof payload.normalizedProfile === 'object'
+        ? payload.normalizedProfile
+        : profile,
+    ),
+    nextAction: normalizeText(
+      payload.nextAction,
+      accepted ? 'join_world_when_membership_persistence_exists' : 'collect_missing_profile_fields',
+    ),
+    profileCollectionFlow:
+      payload.profileCollectionFlow && typeof payload.profileCollectionFlow === 'object'
+        ? payload.profileCollectionFlow
+        : null,
+  };
+}
+
+function normalizeNumber(value, fallback = null) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return parsed;
+}
+
+function normalizeProfileSummaryField(field = {}, index = 0) {
+  const fieldId = normalizeText(field.fieldId || field.id, `field_${index + 1}`);
+  const value = Array.isArray(field.value)
+    ? normalizeStringList(field.value)
+    : normalizeText(field.value, null);
+
+  if (value == null || (Array.isArray(value) && value.length === 0)) {
+    return null;
+  }
+
+  return {
+    fieldId,
+    label: normalizeText(field.label, fieldId),
+    value,
+  };
+}
+
+function normalizeCandidateProfileSummary(summary = {}) {
+  return {
+    displayName: normalizeText(summary.displayName, null),
+    headline: normalizeText(summary.headline, null),
+    requiredFields: Array.isArray(summary.requiredFields)
+      ? summary.requiredFields.map((field, index) => normalizeProfileSummaryField(field, index)).filter(Boolean)
+      : [],
+    optionalFields: Array.isArray(summary.optionalFields)
+      ? summary.optionalFields.map((field, index) => normalizeProfileSummaryField(field, index)).filter(Boolean)
+      : [],
+  };
+}
+
+function normalizeCompatibilitySignal(signal = {}, index = 0) {
+  return {
+    signalId: normalizeText(signal.signalId, `signal_${index + 1}`),
+    type: normalizeText(signal.type, 'world_ready'),
+    fieldIds: normalizeStringList(signal.fieldIds),
+    score: normalizeNumber(signal.score, 0),
+    summary: normalizeText(signal.summary, ''),
+  };
+}
+
+function normalizeDeliveryReason(reason = {}) {
+  return {
+    code: normalizeText(reason.code, null),
+    matchedFieldIds: normalizeStringList(reason.matchedFieldIds),
+    summary: normalizeText(reason.summary, ''),
+  };
+}
+
+function normalizeCandidateScoreBreakdown(entries = []) {
+  if (!Array.isArray(entries)) return [];
+
+  return entries.map((entry, index) => ({
+    signalId: normalizeText(entry.signalId, `score_signal_${index + 1}`),
+    label: normalizeText(entry.label, `Signal ${index + 1}`),
+    weight: normalizeNumber(entry.weight, 0),
+    sourceFieldIds: normalizeStringList(entry.sourceFieldIds),
+    matched: entry.matched === true,
+    requesterValue: entry.requesterValue ?? null,
+    candidateValue: entry.candidateValue ?? null,
+    sharedValues: Array.isArray(entry.sharedValues) ? normalizeStringList(entry.sharedValues) : [],
+    overlapCount: normalizeInteger(entry.overlapCount, 0),
+    contribution: normalizeNumber(entry.contribution, 0),
+  }));
+}
+
+function normalizeCandidate(candidate = {}, index = 0) {
+  const normalizedRank = normalizeNumber(candidate.rank, null);
+
+  return {
+    candidateId: normalizeText(candidate.candidateId, `candidate_${index + 1}`),
+    worldId: normalizeText(candidate.worldId, 'unknown-world'),
+    sourceMembershipId: normalizeText(candidate.sourceMembershipId, null),
+    profileSummary: normalizeCandidateProfileSummary(candidate.profileSummary),
+    compatibilitySignals: Array.isArray(candidate.compatibilitySignals)
+      ? candidate.compatibilitySignals.map((signal, signalIndex) => normalizeCompatibilitySignal(signal, signalIndex))
+      : [],
+    deliveryReason: normalizeDeliveryReason(candidate.deliveryReason),
+    expiresAt: normalizeText(candidate.expiresAt, null),
+    joinedAt: normalizeText(candidate.joinedAt, null),
+    rank: normalizedRank == null ? null : Math.max(1, Math.trunc(normalizedRank)),
+    score: normalizeNumber(candidate.score, null),
+    scoreBreakdown: normalizeCandidateScoreBreakdown(candidate.scoreBreakdown),
+    scoringInputs: candidate.scoringInputs && typeof candidate.scoringInputs === 'object' ? candidate.scoringInputs : {},
+  };
+}
+
+function normalizeCandidateFeedResponse(payload = {}, { worldId = null, agentId = null } = {}) {
+  const candidates = Array.isArray(payload.candidates)
+    ? payload.candidates.map((candidate, index) => normalizeCandidate(candidate, index))
+    : [];
+
+  return {
+    worldId: normalizeText(payload.worldId, worldId || 'unknown-world'),
+    agentId: normalizeText(payload.agentId, agentId || null),
+    viewerMembershipId: normalizeText(payload.viewerMembershipId, null),
+    generatedAt: normalizeText(payload.generatedAt, null),
+    expiresAt: normalizeText(payload.expiresAt, null),
+    deliveryMode: normalizeText(payload.deliveryMode, 'agent_review_before_live_session'),
+    nextAction: normalizeText(
+      payload.nextAction,
+      candidates.length > 0 ? 'review_candidates_before_requesting_live_session' : 'wait_for_more_candidates',
+    ),
+    candidateDelivery: payload.candidateDelivery && typeof payload.candidateDelivery === 'object'
+      ? payload.candidateDelivery
+      : null,
+    candidateSource: normalizeText(payload.candidateSource, 'active_memberships'),
+    candidateModel: payload.candidateModel && typeof payload.candidateModel === 'object' ? payload.candidateModel : {},
+    strategy: payload.strategy && typeof payload.strategy === 'object' ? payload.strategy : {},
+    limit: normalizeInteger(payload.limit, candidates.length),
+    totalCandidates: normalizeInteger(payload.totalCandidates, candidates.length),
+    status: normalizeText(payload.status, candidates.length > 0 ? 'feed_ready' : 'no_candidates_ready'),
+    candidates,
+  };
+}
+
+function normalizeWorldJoinResponse(payload = {}, { worldId = null, agentId = null } = {}) {
+  const membership = payload.membership && typeof payload.membership === 'object' ? payload.membership : null;
+
+  return {
+    worldId: normalizeText(payload.worldId, worldId || 'unknown-world'),
+    agentId: normalizeText(payload.agentId || membership?.agentId, agentId || null),
+    membershipStatus: normalizeText(payload.membershipStatus || membership?.status, 'unknown'),
+    membership,
+    nextStageSummary: payload.nextStageSummary && typeof payload.nextStageSummary === 'object'
+      ? payload.nextStageSummary
+      : {},
+    orchestration: payload.orchestration && typeof payload.orchestration === 'object'
+      ? payload.orchestration
+      : null,
+  };
+}
+
+function projectMissingRequiredFields(fields = []) {
+  return fields.map((field) => ({
+    fieldId: field.fieldId,
+    label: field.label,
+    description: field.description || null,
+  }));
+}
+
+function buildJoinRequestBody({ agentId = null, profile = {}, profileSnapshot = null } = {}) {
+  const normalizedAgentId = normalizeText(agentId, null);
+  const normalizedProfile = normalizeProfile(profile);
+  const normalizedProfileSnapshot = normalizeProfile(profileSnapshot);
+
+  return {
+    agentId: normalizedAgentId,
+    ...(Object.keys(normalizedProfileSnapshot).length > 0
+      ? { profileSnapshot: normalizedProfileSnapshot }
+      : (Object.keys(normalizedProfile).length > 0 ? { profile: normalizedProfile } : {})),
+  };
+}
+
+function resolveJoinSubmissionProfile({
+  profile = {},
+  profileSnapshot = null,
+  profileUpdate = null,
+  profilePatch = null,
+} = {}) {
+  const normalizedProfile = normalizeProfile(profile);
+  const normalizedProfileSnapshot = normalizeProfile(profileSnapshot);
+  const appliedProfileUpdate = normalizeProfile(profileUpdate || profilePatch || {});
+  const baseProfile = Object.keys(normalizedProfileSnapshot).length > 0
+    ? normalizedProfileSnapshot
+    : normalizedProfile;
+
+  return {
+    baseProfile,
+    appliedProfileUpdate,
+    mergedProfile: mergeProfileState(baseProfile, appliedProfileUpdate),
+    preferProfileSnapshot:
+      Object.keys(normalizedProfileSnapshot).length > 0
+      || Object.keys(appliedProfileUpdate).length > 0,
+  };
+}
+
+function normalizeSearchMatchedField(field = {}, index = 0) {
+  return {
+    fieldId: normalizeText(field.fieldId, `field_${index + 1}`),
+    label: normalizeText(field.label, `Field ${index + 1}`),
+    matchType: normalizeText(field.matchType, 'exact'),
+    queryValue: field.queryValue ?? null,
+    candidateValue: field.candidateValue ?? null,
+    sharedValues: Array.isArray(field.sharedValues) ? normalizeStringList(field.sharedValues) : [],
+    contribution: normalizeNumber(field.contribution, 0),
+  };
+}
+
+function normalizeWorldSearchItem(item = {}, index = 0) {
+  const resolvedAgentId = normalizeText(item.agentId, normalizeText(item.playerId, `agent_${index + 1}`));
+  return {
+    agentId: resolvedAgentId,
+    playerId: normalizeText(item.playerId, resolvedAgentId),
+    membershipId: normalizeText(item.membershipId, null),
+    worldId: normalizeText(item.worldId, 'unknown-world'),
+    displayName: normalizeText(item.displayName, `Player ${index + 1}`),
+    headline: normalizeText(item.headline, null),
+    address: normalizeText(item.address, null),
+    online: item.online === true,
+    connectedAt: normalizeText(item.connectedAt, null),
+    lastHeartbeatAt: normalizeText(item.lastHeartbeatAt, null),
+    score: normalizeNumber(item.score, 0),
+    matchedFieldIds: normalizeStringList(item.matchedFieldIds),
+    matchedFields: Array.isArray(item.matchedFields)
+      ? item.matchedFields.map((field, fieldIndex) => normalizeSearchMatchedField(field, fieldIndex))
+      : [],
+    resultType: normalizeText(item.resultType, 'matched'),
+    reasonSummary: normalizeText(item.reasonSummary, ''),
+    joinedAt: normalizeText(item.joinedAt, null),
+    profileSummary: normalizeCandidateProfileSummary(item.profileSummary),
+  };
+}
+
+function normalizeWorldSearchResponse(payload = {}, { worldId = null, agentId = null } = {}) {
+  const items = Array.isArray(payload.items)
+    ? payload.items.map((item, index) => normalizeWorldSearchItem(item, index))
+    : [];
+
+  return {
+    worldId: normalizeText(payload.worldId, worldId || 'unknown-world'),
+    agentId: normalizeText(payload.agentId, agentId || null),
+    viewerMembershipId: normalizeText(payload.viewerMembershipId, null),
+    searchModel: normalizeSearchSchema(payload.searchModel || {}, {
+      worldId: normalizeText(payload.worldId, worldId || 'unknown-world'),
+      fallbackFields: [],
+    }),
+    searchInput: normalizeProfile(payload.searchInput && typeof payload.searchInput === 'object' ? payload.searchInput : {}),
+    onlineOnly: payload.onlineOnly !== false,
+    candidateSource: normalizeText(payload.candidateSource, 'active_memberships_online'),
+    limit: normalizeInteger(payload.limit, items.length),
+    totalMatches: normalizeInteger(payload.totalMatches, items.length),
+    status: normalizeText(payload.status, items.length > 0 ? 'search_ready' : 'no_matches'),
+    nextAction: normalizeText(
+      payload.nextAction,
+      items.length > 0 ? 'select_player_and_start_conversation' : 'broaden_search_or_wait',
+    ),
+    items,
+  };
+}
+
+function summarizeProfileValue(value) {
+  if (Array.isArray(value)) return joinAsNaturalLanguage(value.map((entry) => String(entry).trim()).filter(Boolean));
+  return normalizeText(value, '');
+}
+
+function summarizeProfileFields(fields = []) {
+  return fields
+    .map((field) => {
+      const value = summarizeProfileValue(field.value);
+      if (!value) return null;
+      return `${field.label}: ${value}`;
+    })
+    .filter(Boolean);
+}
+
+function buildCandidateDeliverySummaryLine(candidateSummary = {}, index = 0) {
+  return `${index + 1}. ${candidateSummary.summary}`;
+}
+
+export function buildCandidateDeliverySummary(candidateFeed = {}, { worldDetail = null, limit = null } = {}) {
+  if (candidateFeed?.candidateDelivery && typeof candidateFeed.candidateDelivery === 'object') {
+    return candidateFeed.candidateDelivery;
+  }
+  if (worldDetail?.candidateDelivery && typeof worldDetail.candidateDelivery === 'object') {
+    return worldDetail.candidateDelivery;
+  }
+  // Older responses may still omit candidateDelivery; keep the shared builder as
+  // a compatibility fallback, not the canonical orchestration owner.
+  return buildBackendCandidateDeliverySummary(candidateFeed, { worldDetail, limit });
+}
+
+function buildFieldLookup(worldDetail = {}) {
+  const detail = normalizeWorldDetail(worldDetail);
+  return new Map(
+    [...detail.requiredFields, ...detail.optionalFields].map((field) => [field.fieldId, field]),
+  );
+}
+
+function selectPromptFields(joinCheck = {}, worldDetail = {}, maxFieldsPerStep = 1) {
+  if (joinCheck.accepted) return [];
+
+  const fieldLookup = buildFieldLookup(worldDetail);
+  const orderedMissingFields = Array.isArray(joinCheck.missingFieldGuidance?.orderedMissingFields)
+    && joinCheck.missingFieldGuidance.orderedMissingFields.length > 0
+    ? joinCheck.missingFieldGuidance.orderedMissingFields
+    : (Array.isArray(joinCheck.missingFields) ? joinCheck.missingFields : []);
+
+  return orderedMissingFields.slice(0, Math.max(1, maxFieldsPerStep)).map((field, index) => {
+    const detailField = fieldLookup.get(field.fieldId) || {};
+    return normalizeField(
+      {
+        ...detailField,
+        ...field,
+        description: normalizeText(field.description, detailField.description || null),
+        examples: Array.isArray(detailField.examples) ? detailField.examples : field.examples,
+        constraints: detailField.constraints || field.constraints,
+      },
+      index,
+      { required: true },
+    );
+  });
+}
+
+function buildProfileFieldPrompt(field = {}, index = 0, total = 1) {
+  const examples = Array.isArray(field.examples) && field.examples.length > 0
+    ? ` Example: ${field.examples.map((example) => quoteExample(example)).join(' or ')}.`
+    : '';
+  const description = sentenceCase(
+    field.description || `Provide ${field.label} so the world can evaluate the profile`,
+    'Provide this field so the world can evaluate the profile.',
+  );
+  const prefix = total > 1 ? `${index + 1}. ` : '';
+
+  return `${prefix}${field.label}. ${description}${examples}`;
+}
+
+function listProvidedRequiredFieldIds(worldDetail = {}, profile = {}, missingFieldIds = []) {
+  const missingSet = new Set(normalizeStringList(missingFieldIds));
+  return normalizeWorldDetail(worldDetail).requiredFields
+    .filter((field) => !missingSet.has(field.fieldId) && !isEmptyProfileValue(profile[field.fieldId]))
+    .map((field) => field.fieldId);
+}
+
+function buildProfileCollectionFollowUp(promptFields = []) {
+  if (promptFields.length === 0) {
+    return 'The current profile is already eligible. Continue with the next world step without restarting profile collection.';
+  }
+
+  const labels = promptFields.map((field) => field.label);
+  if (promptFields.length === 1) {
+    return `After the user answers ${labels[0]}, merge it into the saved profile draft and re-run join-check before asking anything else.`;
+  }
+
+  return `After the user answers ${joinAsNaturalLanguage(labels)}, merge those fields into the saved profile draft and re-run join-check before asking anything else.`;
+}
+
+function normalizeSelectionInput(selection) {
+  if (selection && typeof selection === 'object') {
+    const asWorldId = normalizeText(selection.worldId, null);
+    const asDisplayName = normalizeText(selection.displayName, null);
+    const asChoice = normalizeText(selection.selection || selection.choice || selection.value, null);
+    const text = asWorldId || asDisplayName || asChoice || '';
+    return {
+      raw: selection,
+      text,
+      normalized: normalizeLookupText(text),
+      index: /^\d+$/.test(String(text)) ? normalizeInteger(text, 0) : null,
+    };
+  }
+
+  const text = normalizeText(selection, '');
+  return {
+    raw: selection,
+    text,
+    normalized: normalizeLookupText(text),
+    index: /^\d+$/.test(String(text)) ? normalizeInteger(text, 0) : null,
+  };
+}
+
+function buildSelectionRetryContract(status, selection, items = [], matches = []) {
+  const choiceLabel = selection.text ? `"${selection.text}"` : 'that choice';
+  const retryWorlds = (matches.length > 0 ? matches : items).map((world) => normalizeWorldSummary(world));
+  const retrySummary = summarizeWorldChoices(retryWorlds);
+
+  if (status === 'ambiguous') {
+    return {
+      status,
+      selection: {
+        input: selection.text || null,
+        matchedBy: null,
+        worldId: null,
+        displayName: null,
+      },
+      candidateWorlds: retryWorlds,
+      orchestration: {
+        stage: 'post_setup_world_selection_retry',
+        system: 'The world choice matched multiple worlds. Show the narrowed list and ask the user to pick one exact world ID or display name.',
+        user: `The choice ${choiceLabel} is ambiguous. Matching worlds: ${joinAsNaturalLanguage(retrySummary)}. Ask the user to choose one exact world ID or display name.`,
+        followUp: 'Once the user confirms one exact world, fetch its detail and explain the required fields before join-check.',
+      },
+    };
+  }
+
+  return {
+    status: 'no_match',
+    selection: {
+      input: selection.text || null,
+      matchedBy: null,
+      worldId: null,
+      displayName: null,
+    },
+    candidateWorlds: retryWorlds,
+    orchestration: {
+      stage: 'post_setup_world_selection_retry',
+      system: 'The world choice did not match the available world directory. Re-list the worlds and ask the user to choose one by world ID or display name.',
+      user: retrySummary.length > 0
+        ? `I could not match ${choiceLabel} to an available world. Available worlds: ${joinAsNaturalLanguage(retrySummary)}. Ask the user to choose one by world ID or display name.`
+        : 'No worlds are currently available. Tell the user setup is complete but world selection cannot continue yet.',
+      followUp: 'Once the user chooses a valid world, confirm it, fetch the world detail, and explain the required fields before join-check.',
+    },
+  };
+}
+
+export function buildWorldSelectionPrompt(worldDirectory = {}) {
+  if (worldDirectory?.orchestration && typeof worldDirectory.orchestration === 'object') {
+    return worldDirectory.orchestration;
+  }
+  // Compatibility fallback for older directory payloads that predate
+  // backend-authored orchestration.
+  return buildBackendWorldSelectionPrompt(worldDirectory);
+}
+
+export function buildPostSetupWorldDirectory(payload = {}, { accountId = null } = {}) {
+  const items = Array.isArray(payload.items) ? payload.items.map((world) => normalizeWorldSummary(world)) : [];
+  const recommendedWorldId = items[0]?.worldId || null;
+  const pagination = payload.pagination && typeof payload.pagination === 'object'
+    ? {
+      page: normalizeInteger(payload.pagination.page, 1) || 1,
+      totalPages: normalizeInteger(payload.pagination.totalPages, 0),
+      totalCount: normalizeInteger(payload.pagination.totalCount, items.length),
+    }
+    : {
+      page: 1,
+      totalPages: items.length > 0 ? 1 : 0,
+      totalCount: items.length,
+    };
+  const sort = normalizeText(payload.sort, 'hot');
+
+  return {
+    status: 'ready',
+    source: 'product_shell',
+    accountId: normalizeText(accountId, null),
+    worldCount: pagination.totalCount,
+    recommendedWorldId,
+    items,
+    pagination,
+    sort,
+    orchestration: payload.orchestration && typeof payload.orchestration === 'object'
+      ? payload.orchestration
+      : buildWorldSelectionPrompt({ items, recommendedWorldId }),
+  };
+}
+
+export function resolveWorldSelection(worldDirectory = {}, selection = null) {
+  return resolveBackendWorldSelection(worldDirectory, selection);
+}
+
+async function fetchJson(fetchImpl, url, init = {}) {
+  let response;
+  try {
+    response = await fetchImpl(url, init);
+  } catch (error) {
+    throw createRuntimeBoundaryError({
+      code: 'relay_fetch_failed',
+      category: 'transport',
+      status: 502,
+      message: `fetch failed: ${error?.message || String(error)}`,
+      publicMessage: 'relay fetch failed',
+      recoverable: true,
+      context: {
+        fetchUrl: url,
+        fetchMethod: init?.method || 'GET',
+      },
+      cause: error,
+    });
+  }
+  let body = null;
+
+  try {
+    body = await response.json();
+  } catch {
+    body = null;
+  }
+
+  return { ok: response.ok, status: response.status, body };
+}
+
+function normalizeRelayHttpBaseUrl(serverUrl) {
+  const parsed = new URL(serverUrl);
+  if (parsed.protocol === 'ws:') parsed.protocol = 'http:';
+  if (parsed.protocol === 'wss:') parsed.protocol = 'https:';
+  parsed.pathname = '';
+  parsed.search = '';
+  parsed.hash = '';
+  return parsed.toString().replace(/\/$/, '');
+}
+
+function inferHttpErrorCategory(status) {
+  if (status === 401) return 'auth';
+  if (status === 403) return 'policy';
+  if (status === 409) return 'conflict';
+  if (status >= 400 && status < 500) return 'input';
+  return 'runtime';
+}
+
+function createProductShellHttpError(action, response, { accountId = null, worldId = null } = {}) {
+  const backendCode = normalizeText(response?.body?.error, null);
+  const backendMessage = normalizeText(response?.body?.message, `claworld product-shell ${action} failed`);
+
+  return createRuntimeBoundaryError({
+    code: backendCode || `claworld_product_shell_${action}_failed`,
+    category: inferHttpErrorCategory(response?.status),
+    status: response?.status ?? 500,
+    message: `claworld product-shell ${action} failed: ${response?.status ?? 500}`,
+    publicMessage: backendMessage,
+    recoverable: Number(response?.status) >= 400 && Number(response?.status) < 500,
+    context: {
+      action,
+      accountId,
+      ...(worldId ? { worldId } : {}),
+      httpStatus: response?.status ?? 500,
+      backendCode,
+      backendMessage,
+    },
+  });
+}
+
+function normalizeBroadcastRequestPayload(payload = {}, { message = null } = {}) {
+  const normalizedPayload = payload && typeof payload === 'object' && !Array.isArray(payload)
+    ? { ...payload }
+    : {};
+  const normalizedMessage = normalizeText(message, null);
+  if (!normalizedMessage) return normalizedPayload;
+  return {
+    ...normalizedPayload,
+    ...(normalizedPayload.text == null ? { text: normalizedMessage } : {}),
+  };
+}
+
+function normalizeBroadcastResult(payload = {}) {
+  const requests = Array.isArray(payload.requests)
+    ? payload.requests.map((request) => ({
+      agentId: normalizeText(request.agentId, null),
+      status: normalizeText(request.status, 'created'),
+      chatRequest: request.chatRequest && typeof request.chatRequest === 'object' && !Array.isArray(request.chatRequest)
+        ? request.chatRequest
+        : null,
+    }))
+    : [];
+  const failures = Array.isArray(payload.failures)
+    ? payload.failures.map((failure) => ({
+      agentId: normalizeText(failure.agentId, null),
+      status: normalizeText(failure.status, 'failed'),
+      httpStatus: normalizeInteger(failure.httpStatus, 0),
+      error: normalizeText(failure.error, null),
+      reason: normalizeText(failure.reason, null),
+      message: normalizeText(failure.message, null),
+    }))
+    : [];
+  return {
+    status: normalizeText(payload.status, 'requests_created'),
+    worldId: normalizeText(payload.worldId, null),
+    senderAgentId: normalizeText(payload.senderAgentId, null),
+    senderRole: normalizeText(payload.senderRole, 'none'),
+    audience: normalizeText(payload.audience, 'members'),
+    excludeSelf: payload.excludeSelf !== false,
+    eligibility: normalizeText(payload.eligibility, 'active'),
+    broadcastId: normalizeText(payload.broadcastId, null),
+    totalTargets: normalizeInteger(payload.totalTargets, 0),
+    createdCount: normalizeInteger(payload.createdCount, requests.length),
+    failedCount: normalizeInteger(payload.failedCount, failures.length),
+    nextAction: normalizeText(payload.nextAction, 'recipients_review_pending_requests'),
+    requests,
+    failures,
+  };
+}
+
+export async function fetchWorldDetail({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  worldId = null,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for claworld product-shell detail helper');
+  }
+
+  const resolvedWorldId = normalizeText(worldId, null);
+  if (!resolvedWorldId) {
+    throw new Error('claworld product-shell detail helper requires worldId');
+  }
+
+  const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+  const detail = await fetchJson(fetchImpl, `${baseUrl}/v1/worlds/${encodeURIComponent(resolvedWorldId)}`, {
+    headers: {
+      accept: 'application/json',
+      ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+      ...(resolvedRuntimeConfig.relay?.credentialToken ? { 'x-relay-token': resolvedRuntimeConfig.relay.credentialToken } : {}),
+    },
+  });
+
+  if (!detail.ok) {
+    logger.error?.('[claworld:product-shell] world detail fetch failed', {
+      status: detail.status,
+      worldId: resolvedWorldId,
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      body: detail.body,
+    });
+    throw new Error(`claworld product-shell world detail fetch failed: ${detail.status}`);
+  }
+
+  return normalizeWorldDetail(detail.body);
+}
+
+export async function fetchWorldJoinCheck({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  worldId = null,
+  profile = {},
+  maxFieldsPerStep = null,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for claworld product-shell join-check helper');
+  }
+
+  const resolvedWorldId = normalizeText(worldId, null);
+  if (!resolvedWorldId) {
+    throw new Error('claworld product-shell join-check helper requires worldId');
+  }
+
+  const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+  const normalizedProfile = normalizeProfile(profile);
+  const joinCheck = await fetchJson(fetchImpl, `${baseUrl}/v1/worlds/${encodeURIComponent(resolvedWorldId)}/join-check`, {
+    method: 'POST',
+    headers: {
+      accept: 'application/json',
+      'content-type': 'application/json',
+      ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+      ...(resolvedRuntimeConfig.relay?.credentialToken ? { 'x-relay-token': resolvedRuntimeConfig.relay.credentialToken } : {}),
+    },
+    body: JSON.stringify({
+      profile: normalizedProfile,
+      ...(maxFieldsPerStep == null ? {} : { maxFieldsPerStep }),
+    }),
+  });
+
+  if (!joinCheck.ok && joinCheck.status !== 422) {
+    logger.error?.('[claworld:product-shell] world join-check failed', {
+      status: joinCheck.status,
+      worldId: resolvedWorldId,
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      body: joinCheck.body,
+    });
+    throw new Error(`claworld product-shell join-check failed: ${joinCheck.status}`);
+  }
+
+  return normalizeJoinCheckResponse(joinCheck.body, {
+    worldId: resolvedWorldId,
+    profile: normalizedProfile,
+  });
+}
+
+export async function joinWorld({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  worldId = null,
+  agentId = null,
+  profile = {},
+  profileSnapshot = null,
+  maxFieldsPerStep = null,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for claworld product-shell join helper');
+  }
+
+  const resolvedWorldId = normalizeText(worldId, null);
+  if (!resolvedWorldId) {
+    throw new Error('claworld product-shell join helper requires worldId');
+  }
+
+  const resolvedAgentId = normalizeText(agentId, null);
+  if (!resolvedAgentId) {
+    throw new Error('claworld product-shell join helper requires agentId');
+  }
+
+  const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+  const requestBody = buildJoinRequestBody({
+    agentId: resolvedAgentId,
+    profile,
+    profileSnapshot,
+  });
+  if (maxFieldsPerStep != null) {
+    requestBody.maxFieldsPerStep = maxFieldsPerStep;
+  }
+  const joinResult = await fetchJson(fetchImpl, `${baseUrl}/v1/worlds/${encodeURIComponent(resolvedWorldId)}/join`, {
+    method: 'POST',
+    headers: {
+      accept: 'application/json',
+      'content-type': 'application/json',
+      ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+      ...(resolvedRuntimeConfig.relay?.credentialToken ? { 'x-relay-token': resolvedRuntimeConfig.relay.credentialToken } : {}),
+    },
+    body: JSON.stringify(requestBody),
+  });
+
+  if (!joinResult.ok) {
+    logger.error?.('[claworld:product-shell] world join failed', {
+      status: joinResult.status,
+      worldId: resolvedWorldId,
+      agentId: resolvedAgentId,
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      body: joinResult.body,
+    });
+    throw new Error(`claworld product-shell world join failed: ${joinResult.status}`);
+  }
+
+  return normalizeWorldJoinResponse(joinResult.body, {
+    worldId: resolvedWorldId,
+    agentId: resolvedAgentId,
+  });
+}
+
+export async function submitWorldJoin({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  worldId = null,
+  agentId = null,
+  profile = {},
+  profileSnapshot = null,
+  profileUpdate = null,
+  profilePatch = null,
+  worldDetail = null,
+  maxFieldsPerStep = 1,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for claworld product-shell join helper');
+  }
+
+  const resolvedWorldId = normalizeText(worldId, null);
+  if (!resolvedWorldId) {
+    throw new Error('claworld product-shell join helper requires worldId');
+  }
+
+  const resolvedAgentId = normalizeText(agentId, null);
+  if (!resolvedAgentId) {
+    throw new Error('claworld product-shell join helper requires agentId');
+  }
+
+  const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+  const joinProfile = resolveJoinSubmissionProfile({
+    profile,
+    profileSnapshot,
+    profileUpdate,
+    profilePatch,
+  });
+  const requestBody = buildJoinRequestBody({
+    agentId: resolvedAgentId,
+    profile: joinProfile.mergedProfile,
+    profileSnapshot: joinProfile.preferProfileSnapshot ? joinProfile.mergedProfile : null,
+  });
+  if (maxFieldsPerStep != null) {
+    requestBody.maxFieldsPerStep = maxFieldsPerStep;
+  }
+  const joinResult = await fetchJson(fetchImpl, `${baseUrl}/v1/worlds/${encodeURIComponent(resolvedWorldId)}/join`, {
+    method: 'POST',
+    headers: {
+      accept: 'application/json',
+      'content-type': 'application/json',
+      ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+      ...(resolvedRuntimeConfig.relay?.credentialToken ? { 'x-relay-token': resolvedRuntimeConfig.relay.credentialToken } : {}),
+    },
+    body: JSON.stringify(requestBody),
+  });
+
+  if (!joinResult.ok && joinResult.status !== 422) {
+    logger.error?.('[claworld:product-shell] world join failed', {
+      status: joinResult.status,
+      worldId: resolvedWorldId,
+      agentId: resolvedAgentId,
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      body: joinResult.body,
+    });
+    throw new Error(`claworld product-shell world join failed: ${joinResult.status}`);
+  }
+
+  if (joinResult.status === 422) {
+    const detail = worldDetail
+      ? normalizeWorldDetail(worldDetail)
+      : await fetchWorldDetail({
+        cfg,
+        accountId,
+        runtimeConfig: resolvedRuntimeConfig,
+        worldId: resolvedWorldId,
+        fetchImpl,
+        logger,
+      });
+    const joinCheck = normalizeJoinCheckResponse(joinResult.body?.joinCheck || joinResult.body, {
+      worldId: resolvedWorldId,
+      profile: joinProfile.mergedProfile,
+    });
+    const profileCollectionFlow = joinCheck.profileCollectionFlow && typeof joinCheck.profileCollectionFlow === 'object'
+      ? {
+        ...joinCheck.profileCollectionFlow,
+        worldDetail: detail,
+        joinCheck,
+        profile: joinCheck.normalizedProfile,
+        appliedProfileUpdate: joinProfile.appliedProfileUpdate,
+      }
+      : {
+        ...buildBackendWorldProfileCollectionFlow({
+          worldDetail: detail,
+          joinCheck,
+          profile: joinCheck.normalizedProfile,
+          maxFieldsPerStep,
+        }),
+        worldDetail: detail,
+        joinCheck,
+        profile: joinCheck.normalizedProfile,
+        appliedProfileUpdate: joinProfile.appliedProfileUpdate,
+      };
+
+    return {
+      status: 'needs_profile',
+      worldId: resolvedWorldId,
+      agentId: resolvedAgentId,
+      membershipStatus: normalizeText(joinResult.body?.membershipStatus, 'inactive'),
+      searchEnabled: false,
+      missingRequiredFields: projectMissingRequiredFields(joinCheck.missingFields),
+      nextMissingField: joinCheck.nextMissingField
+        ? projectMissingRequiredFields([joinCheck.nextMissingField])[0]
+        : null,
+      normalizedProfile: profileCollectionFlow.profile,
+      nextAction: 'complete_required_profile_fields_then_retry_join',
+      joinCheck,
+      profileCollectionFlow,
+      orchestration: profileCollectionFlow.orchestration || null,
+      providedRequiredFieldIds: profileCollectionFlow.providedRequiredFieldIds,
+      promptFields: profileCollectionFlow.promptFields,
+      remainingRequiredFieldCount: profileCollectionFlow.remainingRequiredFieldCount,
+      revalidationCheckpoint: profileCollectionFlow.revalidationCheckpoint,
+    };
+  }
+
+  const normalizedJoinResult = normalizeWorldJoinResponse(joinResult.body, {
+    worldId: resolvedWorldId,
+    agentId: resolvedAgentId,
+  });
+
+  return {
+    status: normalizedJoinResult.membershipStatus === 'active' ? 'activated' : 'accepted',
+    worldId: normalizedJoinResult.worldId,
+    agentId: normalizedJoinResult.agentId,
+    membershipStatus: normalizedJoinResult.membershipStatus,
+    searchEnabled: normalizedJoinResult.membershipStatus === 'active',
+    membership: normalizedJoinResult.membership,
+    nextStageSummary: normalizedJoinResult.nextStageSummary,
+    orchestration: normalizedJoinResult.orchestration || null,
+  };
+}
+
+export async function fetchWorldSearch({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  worldId = null,
+  agentId = null,
+  query = {},
+  limit = null,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for claworld product-shell world search helper');
+  }
+
+  const resolvedWorldId = normalizeText(worldId, null);
+  if (!resolvedWorldId) {
+    throw new Error('claworld product-shell world search helper requires worldId');
+  }
+
+  const resolvedAgentId = normalizeText(agentId, null);
+  if (!resolvedAgentId) {
+    throw new Error('claworld product-shell world search helper requires agentId');
+  }
+
+  const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+  const normalizedQuery = normalizeProfile(query);
+  const searchResult = await fetchJson(fetchImpl, `${baseUrl}/v1/worlds/${encodeURIComponent(resolvedWorldId)}/search`, {
+    method: 'POST',
+    headers: {
+      accept: 'application/json',
+      'content-type': 'application/json',
+      ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+      ...(resolvedRuntimeConfig.relay?.credentialToken ? { 'x-relay-token': resolvedRuntimeConfig.relay.credentialToken } : {}),
+    },
+    body: JSON.stringify({
+      agentId: resolvedAgentId,
+      query: normalizedQuery,
+      ...(limit != null ? { limit } : {}),
+    }),
+  });
+
+  if (!searchResult.ok) {
+    logger.error?.('[claworld:product-shell] world search failed', {
+      status: searchResult.status,
+      worldId: resolvedWorldId,
+      agentId: resolvedAgentId,
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      body: searchResult.body,
+    });
+    throw new Error(`claworld product-shell world search failed: ${searchResult.status}`);
+  }
+
+  return normalizeWorldSearchResponse(searchResult.body, {
+    worldId: resolvedWorldId,
+    agentId: resolvedAgentId,
+  });
+}
+
+export async function submitWorldSearch({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  worldId = null,
+  agentId = null,
+  query = {},
+  limit = null,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for claworld product-shell world search helper');
+  }
+
+  const resolvedWorldId = normalizeText(worldId, null);
+  if (!resolvedWorldId) {
+    throw new Error('claworld product-shell world search helper requires worldId');
+  }
+
+  const resolvedAgentId = normalizeText(agentId, null);
+  if (!resolvedAgentId) {
+    throw new Error('claworld product-shell world search helper requires agentId');
+  }
+
+  const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+  const normalizedQuery = normalizeProfile(query);
+  const searchResult = await fetchJson(fetchImpl, `${baseUrl}/v1/worlds/${encodeURIComponent(resolvedWorldId)}/search`, {
+    method: 'POST',
+    headers: {
+      accept: 'application/json',
+      'content-type': 'application/json',
+      ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+      ...(resolvedRuntimeConfig.relay?.credentialToken ? { 'x-relay-token': resolvedRuntimeConfig.relay.credentialToken } : {}),
+    },
+    body: JSON.stringify({
+      agentId: resolvedAgentId,
+      query: normalizedQuery,
+      ...(limit != null ? { limit } : {}),
+    }),
+  });
+
+  if (!searchResult.ok && searchResult.status !== 409) {
+    logger.error?.('[claworld:product-shell] world search failed', {
+      status: searchResult.status,
+      worldId: resolvedWorldId,
+      agentId: resolvedAgentId,
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      body: searchResult.body,
+    });
+    throw new Error(`claworld product-shell world search failed: ${searchResult.status}`);
+  }
+
+  if (searchResult.status === 409) {
+    return {
+      status: 'not_joined',
+      worldId: resolvedWorldId,
+      agentId: resolvedAgentId,
+      searchEnabled: false,
+      results: [],
+      query: normalizedQuery,
+      limit: normalizeInteger(limit, 10),
+      message: 'Join the world successfully before using world search.',
+    };
+  }
+
+  const normalizedSearch = normalizeWorldSearchResponse(searchResult.body, {
+    worldId: resolvedWorldId,
+    agentId: resolvedAgentId,
+  });
+
+  return {
+    ...normalizedSearch,
+    status: normalizedSearch.items.length > 0 ? 'ready' : 'empty',
+    searchEnabled: true,
+    results: normalizedSearch.items,
+    query: normalizedSearch.searchInput,
+  };
+}
+
+export async function broadcastWorld({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  worldId = null,
+  agentId = null,
+  message = null,
+  payload = {},
+  audience = null,
+  excludeSelf = null,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for claworld product-shell world broadcast helper');
+  }
+
+  const resolvedWorldId = normalizeText(worldId, null);
+  if (!resolvedWorldId) {
+    throw new Error('claworld product-shell world broadcast helper requires worldId');
+  }
+
+  const resolvedAgentId = normalizeText(agentId, null);
+  if (!resolvedAgentId) {
+    throw new Error('claworld product-shell world broadcast helper requires agentId');
+  }
+
+  const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+  const requestBody = {
+    agentId: resolvedAgentId,
+    payload: normalizeBroadcastRequestPayload(payload, { message }),
+    ...(audience ? { audience } : {}),
+    ...(excludeSelf == null ? {} : { excludeSelf: excludeSelf === true }),
+  };
+  const broadcastResult = await fetchJson(
+    fetchImpl,
+    `${baseUrl}/v1/worlds/${encodeURIComponent(resolvedWorldId)}/broadcast`,
+    {
+      method: 'POST',
+      headers: {
+        accept: 'application/json',
+        'content-type': 'application/json',
+        ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+        ...(resolvedRuntimeConfig.relay?.credentialToken ? { 'x-relay-token': resolvedRuntimeConfig.relay.credentialToken } : {}),
+      },
+      body: JSON.stringify(requestBody),
+    },
+  );
+
+  if (!broadcastResult.ok) {
+    logger.error?.('[claworld:product-shell] world broadcast failed', {
+      status: broadcastResult.status,
+      worldId: resolvedWorldId,
+      agentId: resolvedAgentId,
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      body: broadcastResult.body,
+    });
+    throw createProductShellHttpError('world_broadcast', broadcastResult, {
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      worldId: resolvedWorldId,
+    });
+  }
+
+  return normalizeBroadcastResult(broadcastResult.body);
+}
+
+export async function fetchWorldCandidateFeed({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  worldId = null,
+  agentId = null,
+  limit = null,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for claworld product-shell candidate feed helper');
+  }
+
+  const resolvedWorldId = normalizeText(worldId, null);
+  if (!resolvedWorldId) {
+    throw new Error('claworld product-shell candidate feed helper requires worldId');
+  }
+
+  const resolvedAgentId = normalizeText(agentId, null);
+  if (!resolvedAgentId) {
+    throw new Error('claworld product-shell candidate feed helper requires agentId');
+  }
+
+  const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+  const requestUrl = new URL(`${baseUrl}/v1/worlds/${encodeURIComponent(resolvedWorldId)}/candidates`);
+  requestUrl.searchParams.set('agentId', resolvedAgentId);
+  const normalizedLimit = normalizeInteger(limit, 0);
+  if (normalizedLimit > 0) {
+    requestUrl.searchParams.set('limit', String(normalizedLimit));
+  }
+  const candidateFeed = await fetchJson(fetchImpl, requestUrl.toString(), {
+    headers: {
+      accept: 'application/json',
+      ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+      ...(resolvedRuntimeConfig.relay?.credentialToken ? { 'x-relay-token': resolvedRuntimeConfig.relay.credentialToken } : {}),
+    },
+  });
+
+  if (!candidateFeed.ok) {
+    logger.error?.('[claworld:product-shell] candidate feed fetch failed', {
+      status: candidateFeed.status,
+      worldId: resolvedWorldId,
+      agentId: resolvedAgentId,
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      body: candidateFeed.body,
+    });
+    throw new Error(`claworld product-shell candidate feed failed: ${candidateFeed.status}`);
+  }
+
+  return normalizeCandidateFeedResponse(candidateFeed.body, {
+    worldId: resolvedWorldId,
+    agentId: resolvedAgentId,
+  });
+}
+
+function buildFieldStepPrompt(field = {}, index = 0, total = 1) {
+  const examples = Array.isArray(field.examples) && field.examples.length > 0
+    ? ` Example: ${field.examples.map((example) => quoteExample(example)).join(' or ')}.`
+    : '';
+  const description = sentenceCase(
+    field.description || `Provide ${field.label} so the world can evaluate the profile`,
+    'Provide this field so the world can evaluate the profile.',
+  );
+
+  return `Step ${index + 1} of ${total}: ${field.label}. ${description}${examples}`;
+}
+
+export function buildRequiredFieldExplanation(worldDetail = {}) {
+  if (worldDetail?.requiredFieldExplanation && typeof worldDetail.requiredFieldExplanation === 'object') {
+    return worldDetail.requiredFieldExplanation;
+  }
+  // Compatibility fallback for older world-detail payloads that do not yet
+  // carry backend-authored required-field explanation.
+  return buildBackendRequiredFieldExplanation(worldDetail);
+}
+
+export async function resolveWorldProfileCollectionFlow({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  worldId = null,
+  worldDetail = null,
+  profile = {},
+  profileUpdate = null,
+  profilePatch = null,
+  maxFieldsPerStep = 1,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  const appliedProfileUpdate = normalizeProfile(profileUpdate || profilePatch || {});
+  const mergedProfile = mergeProfileState(profile, appliedProfileUpdate);
+  const detail = worldDetail
+    ? normalizeWorldDetail(worldDetail)
+    : await fetchWorldDetail({
+      cfg,
+      accountId,
+      runtimeConfig,
+      worldId,
+      fetchImpl,
+      logger,
+    });
+  const resolvedWorldId = normalizeText(worldId || detail.worldId, detail.worldId);
+  if (!resolvedWorldId) {
+    throw new Error('claworld product-shell profile collection flow requires worldId');
+  }
+
+  const joinCheck = await fetchWorldJoinCheck({
+    cfg,
+    accountId,
+    runtimeConfig,
+    worldId: resolvedWorldId,
+    profile: mergedProfile,
+    maxFieldsPerStep,
+    fetchImpl,
+    logger,
+  });
+  const backendFlow = joinCheck.profileCollectionFlow && typeof joinCheck.profileCollectionFlow === 'object'
+    ? joinCheck.profileCollectionFlow
+    : buildBackendWorldProfileCollectionFlow({
+      worldDetail: detail,
+      joinCheck,
+      profile: joinCheck.normalizedProfile,
+      maxFieldsPerStep,
+    });
+
+  return {
+    ...backendFlow,
+    appliedProfileUpdate,
+    worldDetail: detail,
+    joinCheck,
+    worldId: resolvedWorldId,
+    displayName: detail.displayName,
+    profile: joinCheck.normalizedProfile,
+    accepted: joinCheck.accepted,
+    status: joinCheck.status,
+  };
+}
+
+export async function resolveWorldSelectionFlow({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  worldDirectory = null,
+  selection = null,
+  profile = {},
+  maxFieldsPerStep = 1,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  const directory = worldDirectory && Array.isArray(worldDirectory.items)
+    ? buildPostSetupWorldDirectory(worldDirectory, { accountId })
+    : await (async () => {
+      if (typeof fetchImpl !== 'function') {
+        throw new Error('fetch is unavailable for claworld product-shell world flow');
+      }
+      const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+      const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+      const worlds = await fetchJson(fetchImpl, `${baseUrl}/v1/worlds`, {
+        headers: {
+          accept: 'application/json',
+          ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+          ...(resolvedRuntimeConfig.relay?.credentialToken ? { 'x-relay-token': resolvedRuntimeConfig.relay.credentialToken } : {}),
+        },
+      });
+
+      if (!worlds.ok) {
+        logger.error?.('[claworld:product-shell] world directory fetch failed during selection flow', {
+          status: worlds.status,
+          accountId: resolvedRuntimeConfig.accountId || accountId || null,
+          body: worlds.body,
+        });
+        throw new Error(`claworld product-shell world fetch failed: ${worlds.status}`);
+      }
+
+      return buildPostSetupWorldDirectory(worlds.body, {
+        accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      });
+    })();
+
+  const resolvedSelection = resolveWorldSelection(directory, selection);
+  if (resolvedSelection.status !== 'selected') {
+    return {
+      ...resolvedSelection,
+      worldDirectory: directory,
+    };
+  }
+
+  const worldDetail = await fetchWorldDetail({
+    cfg,
+    accountId,
+    runtimeConfig,
+    worldId: resolvedSelection.selectedWorld.worldId,
+    fetchImpl,
+    logger,
+  });
+  const requiredFieldExplanation = buildRequiredFieldExplanation(worldDetail);
+  const profileCollectionFlow = await resolveWorldProfileCollectionFlow({
+    cfg,
+    accountId,
+    runtimeConfig,
+    worldId: resolvedSelection.selectedWorld.worldId,
+    worldDetail,
+    profile,
+    maxFieldsPerStep,
+    fetchImpl,
+    logger,
+  });
+
+  return {
+    status: 'selected',
+    source: 'product_shell',
+    worldDirectory: directory,
+    selection: resolvedSelection.selection,
+    selectedWorld: resolvedSelection.selectedWorld,
+    worldDetail,
+    requiredFieldExplanation,
+    profileCollectionFlow,
+    orchestration: resolvedSelection.orchestration || null,
+  };
+}
+
+export async function resolveWorldJoinFlow({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  worldId = null,
+  worldDetail = null,
+  agentId = null,
+  profile = {},
+  profileSnapshot = null,
+  limit = null,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  const detail = worldDetail
+    ? normalizeWorldDetail(worldDetail)
+    : await fetchWorldDetail({
+      cfg,
+      accountId,
+      runtimeConfig,
+      worldId,
+      fetchImpl,
+      logger,
+    });
+  const resolvedWorldId = normalizeText(worldId || detail.worldId, detail.worldId);
+  if (!resolvedWorldId) {
+    throw new Error('claworld product-shell join flow requires worldId');
+  }
+
+  const joinResult = await joinWorld({
+    cfg,
+    accountId,
+    runtimeConfig,
+    worldId: resolvedWorldId,
+    agentId,
+    profile,
+    profileSnapshot,
+    fetchImpl,
+    logger,
+  });
+  const candidateFeed = await fetchWorldCandidateFeed({
+    cfg,
+    accountId,
+    runtimeConfig,
+    worldId: resolvedWorldId,
+    agentId: joinResult.agentId || agentId,
+    limit,
+    fetchImpl,
+    logger,
+  });
+  const candidateDelivery = buildCandidateDeliverySummary(candidateFeed, {
+    worldDetail: detail,
+    limit,
+  });
+  const joinOrchestration = joinResult.orchestration && typeof joinResult.orchestration === 'object'
+    ? joinResult.orchestration
+    : buildBackendWorldJoinOutcomeOrchestration({
+      worldDetail: detail,
+      joinResult,
+    });
+
+  return {
+    status: candidateDelivery.status,
+    source: 'product_shell',
+    worldId: resolvedWorldId,
+    displayName: detail.displayName,
+    agentId: joinResult.agentId || normalizeText(agentId, null),
+    worldDetail: detail,
+    membershipStatus: joinResult.membershipStatus,
+    membership: joinResult.membership,
+    nextStageSummary: joinResult.nextStageSummary,
+    joinResult,
+    candidateFeed,
+    candidateDelivery,
+    orchestration: joinOrchestration,
+  };
+}