@xfxstudio/claworld 0.1.4 → 0.2.0

package/src/product-shell/index.js

@@ -10,7 +10,7 @@ import { createMembershipService } from './membership/membership-service.js';
 import { createMatchmakingService } from './matching/matchmaking-service.js';
 import { createWorldSearchService } from './search/search-service.js';
 import { createResultService } from './results/result-service.js';
-import { createSessionOrchestrator } from './orchestration/session-orchestrator.js';
+import { createWorldConversationOrchestrator } from './orchestration/world-conversation-orchestrator.js';
 import { createSocialService } from './social/social-service.js';
 import { registerSocialRoutes } from './social/social-routes.js';
 import { createFriendService } from './social/friend-service.js';
@@ -33,7 +33,7 @@ export function createClaworldProductShell({
     worldService,
     membershipService,
   });
-  const matchmakingService = createMatchmakingService({ worldService, worldAuthorizationService, store });
+  const matchmakingService = createMatchmakingService({ worldService, worldAuthorizationService, store, presence });
   const searchService = createWorldSearchService({ worldService, worldAuthorizationService, store, presence });
   const worldAdminService = createWorldAdminService({ worldService, worldAuthorizationService, store });
   const chatRequestService = createChatRequestService({
@@ -60,7 +60,7 @@ export function createClaworldProductShell({
       return socialLookupService.lookupAgentByCode(input);
     },
   };
-  const sessionOrchestrator = createSessionOrchestrator({
+  const worldConversationOrchestrator = createWorldConversationOrchestrator({
     worldService,
     resultService,
   });
@@ -79,7 +79,7 @@ export function createClaworldProductShell({
       moderation: worldAdminService,
       feedback: feedbackService,
       results: resultService,
-      orchestration: sessionOrchestrator,
+      orchestration: worldConversationOrchestrator,
     },
     registerRoutes(app) {
       registerOnboardingRoutes(app, { onboardingService, store });
@@ -94,7 +94,7 @@ export function createClaworldProductShell({
         searchService,
         worldBroadcastService,
         worldAdminService,
-        sessionOrchestrator,
+        worldConversationOrchestrator,
       });
       registerSocialRoutes(app, { socialService: socialLookupService });
       registerFeedbackRoutes(app, { store, feedbackService });
@@ -138,11 +138,10 @@ export function createClaworldProductShell({
           'POST /v1/worlds/:worldId/search',
           'POST /v1/worlds/:worldId/broadcast',
           'GET /v1/worlds/:worldId/candidates',
-          'POST /v1/worlds/:worldId/join-check',
           'POST /v1/worlds/:worldId/join',
           'GET /v1/worlds/:worldId/memberships',
           'POST /v1/worlds/:worldId/memberships',
-          'POST /v1/worlds/:worldId/session-preview',
+          'POST /v1/worlds/:worldId/conversation-preview',
           'GET /v1/social/agents/lookup',
           'POST /v1/feedback',
           'GET /v1/moderation/worlds',

package/src/product-shell/matching/matchmaking-service.js

@@ -217,7 +217,14 @@ function buildViewerContext({ world, membershipStore, normalizedAgentId, worldAu
   };
 }
 
-function buildBaseFeed({ world, membershipStore, normalizedAgentId, limit, worldAuthorizationService }) {
+function buildBaseFeed({
+  world,
+  membershipStore,
+  normalizedAgentId,
+  limit,
+  worldAuthorizationService,
+  resolvePresence,
+}) {
   const { viewerAgent, viewerMembership } = buildViewerContext({
     world,
     membershipStore,
@@ -236,6 +243,7 @@ function buildBaseFeed({ world, membershipStore, normalizedAgentId, limit, world
     viewerAgent,
     candidateMemberships: activeMemberships,
     getAgent: (candidateAgentId) => membershipStore.getAgent(candidateAgentId),
+    getPresence: (candidateAgentId) => resolvePresence(candidateAgentId),
     nowMs,
     limit: activeMemberships.length,
   });
@@ -248,13 +256,21 @@ function buildBaseFeed({ world, membershipStore, normalizedAgentId, limit, world
   };
 }
 
-function buildDatingDemoFeed({ world, membershipStore, normalizedAgentId, limit, worldAuthorizationService }) {
+function buildDatingDemoFeed({
+  world,
+  membershipStore,
+  normalizedAgentId,
+  limit,
+  worldAuthorizationService,
+  resolvePresence,
+}) {
   const { viewerMembership, activeMemberships, normalizedLimit, baseFeed } = buildBaseFeed({
     world,
     membershipStore,
     normalizedAgentId,
     limit,
     worldAuthorizationService,
+    resolvePresence,
   });
   const membershipById = new Map(activeMemberships.map((membership) => [membership.membershipId, membership]));
   const rankedCandidates = baseFeed.candidates
@@ -278,19 +294,35 @@ function buildDatingDemoFeed({ world, membershipStore, normalizedAgentId, limit,
     ...baseFeed,
     agentId: normalizedAgentId,
     limit: normalizedLimit,
-    candidateSource: 'active_memberships',
+    candidateSource: 'active_memberships_online',
     strategy: buildStrategy(world),
     totalCandidates: rankedCandidates.length,
     candidates,
   };
 }
 
-export function createMatchmakingService({ worldService, worldAuthorizationService, store = null } = {}) {
+export function createMatchmakingService({
+  worldService,
+  worldAuthorizationService,
+  store = null,
+  presence = null,
+} = {}) {
   function assertStore() {
     if (!store) throw createConfigurationError();
     return store;
   }
 
+  function resolvePresence(agentId) {
+    if (!presence) {
+      return {
+        online: true,
+        connectedAt: null,
+        lastHeartbeatAt: null,
+      };
+    }
+    return presence.getPresence(agentId);
+  }
+
   return {
     describeStrategy(worldId) {
       const world = worldService.requireWorld(worldId);
@@ -312,6 +344,7 @@ export function createMatchmakingService({ worldService, worldAuthorizationServi
           normalizedAgentId,
           limit,
           worldAuthorizationService,
+          resolvePresence,
         });
       }
 
@@ -321,13 +354,14 @@ export function createMatchmakingService({ worldService, worldAuthorizationServi
         normalizedAgentId,
         limit,
         worldAuthorizationService,
+        resolvePresence,
       });
 
       return {
         ...baseFeed,
         agentId: normalizedAgentId,
         limit: normalizedLimit,
-        candidateSource: 'active_memberships',
+        candidateSource: 'active_memberships_online',
         strategy: buildStrategy(world),
         totalCandidates: baseFeed.candidates.length,
         candidates: baseFeed.candidates.slice(0, normalizedLimit),

package/src/product-shell/membership/membership-service.js

@@ -1,21 +1,10 @@
-import {
-  buildWorldJoinOutcomeOrchestration,
-  buildWorldProfileCollectionFlow,
-} from '../contracts/world-orchestration.js';
+import { buildResolvedWorldJoinOrchestration } from '../contracts/world-orchestration.js';
+import { buildParticipantContextText } from '../worlds/world-text.js';
 
-function isEmptyValue(value) {
-  if (value == null) return true;
-  if (typeof value === 'string') return value.trim() === '';
-  if (Array.isArray(value)) return value.length === 0;
-  return false;
-}
-
-function projectMissingField(field = {}) {
-  return {
-    fieldId: field.fieldId,
-    label: field.label,
-    description: field.description,
-  };
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
 }
 
 function createConfigurationError() {
@@ -49,67 +38,30 @@ function createInvalidJoinRequestError(fieldId, message = `${fieldId} is require
   return error;
 }
 
-function createMembershipNotEligibleError(joinCheck) {
-  const error = new Error('membership_not_eligible');
-  error.code = 'membership_not_eligible';
-  error.status = 422;
-  error.responseBody = {
-    error: error.code,
-    message: 'profile does not satisfy world join requirements',
-    joinCheck,
-    profileCollectionFlow: joinCheck.profileCollectionFlow || null,
-  };
-  return error;
-}
-
-function createJoinNotEligibleError(joinCheck) {
-  const error = new Error('world_join_not_eligible');
-  error.code = 'world_join_not_eligible';
-  error.status = 422;
-  error.responseBody = {
-    error: error.code,
-    message: 'profile does not satisfy world join requirements',
-    status: 'needs_profile',
-    membershipStatus: 'inactive',
-    worldId: joinCheck.worldId,
-    normalizedProfile: joinCheck.normalizedProfile,
-    missingFields: joinCheck.missingFields,
-    nextMissingField: joinCheck.nextMissingField,
-    missingFieldGuidance: joinCheck.missingFieldGuidance,
-    nextAction: 'retry_join_world_after_profile_update',
-  };
-  return error;
-}
-
 function normalizeAgentId(agentId) {
   const normalized = String(agentId || '').trim();
   return normalized || null;
 }
 
-function normalizeProfileSnapshot(...candidates) {
-  for (const candidate of candidates) {
-    if (candidate && typeof candidate === 'object' && !Array.isArray(candidate)) {
-      return candidate;
-    }
+function normalizeProfileSnapshot(profileSnapshot = null, participantContextText = null) {
+  const base = profileSnapshot && typeof profileSnapshot === 'object' && !Array.isArray(profileSnapshot)
+    ? { ...profileSnapshot }
+    : {};
+  const normalizedParticipantContextText = normalizeText(
+    participantContextText,
+    normalizeText(base.participantContextText, null),
+  );
+  if (normalizedParticipantContextText) {
+    base.participantContextText = normalizedParticipantContextText;
   }
-  return {};
+  return base;
 }
 
-function buildNextStageSummary(world) {
-  const matchingSummary = world.matching.strategySummary
-    || `The world uses ${world.matching.mode} matching to deliver candidate summaries before request_chat.`;
-  const reviewSummary =
-    'Review the backend-authored candidate feed, choose a candidate, and create a world-scoped chat request.';
-  const sessionSummary = `Matched agents then enter a ${world.sessionTemplate.mode} session with up to ${world.sessionTemplate.maxTurns} turns.`;
-
+function buildNextStageSummary() {
   return {
-    stage: 'matchmaking',
-    summary: `${matchingSummary} ${reviewSummary} ${sessionSummary}`.trim(),
-    matchingMode: world.matching.mode,
-    matchingCadence: world.matching.cadence,
-    sessionMode: world.sessionTemplate.mode,
-    maxTurns: world.sessionTemplate.maxTurns,
-    turnTimeoutMs: world.sessionTemplate.turnTimeoutMs,
+    stage: 'candidate_review',
+    summary:
+      'Review the backend-authored candidate feed or use world search, then choose one target agent and create a world-scoped chat request.',
   };
 }
 
@@ -119,67 +71,86 @@ export function createMembershipService({ worldService, store = null } = {}) {
     return store;
   }
 
+  function resolveNormalizedParticipantContextText({ participantContextText = null, profileSnapshot = null, agent = null, world = null } = {}) {
+    return buildParticipantContextText({
+      world,
+      agent,
+      participantContextText,
+      profileSnapshot,
+    });
+  }
+
   return {
-    evaluateJoin({ worldId, profile = {}, maxFieldsPerStep = 1 } = {}) {
+    evaluateJoin({ worldId, participantContextText = null } = {}) {
       const world = worldService.requireWorld(worldId);
-      const normalizedProfile = profile && typeof profile === 'object' ? profile : {};
-      const orderedMissingFields = world.joinSchema.requiredFields.filter((field) =>
-        isEmptyValue(normalizedProfile[field.fieldId]),
-      );
-      const missingFields = orderedMissingFields.map((field) => projectMissingField(field));
-      const nextMissingField = missingFields[0] || null;
+      const normalizedParticipantContextText = normalizeText(participantContextText, null);
+      const accepted = Boolean(normalizedParticipantContextText);
 
-      const joinCheck = {
+      return {
         worldId: world.worldId,
-        accepted: missingFields.length === 0,
-        status: missingFields.length === 0 ? 'eligible' : 'needs_profile',
-        missingFields,
-        nextMissingField,
+        accepted,
+        status: accepted ? 'eligible' : 'needs_profile',
+        participantContextText: normalizedParticipantContextText,
+        missingFields: accepted
+          ? []
+          : [
+            {
+              fieldId: 'participantContextText',
+              label: 'Entry Profile',
+              description: 'A short text describing who you are in this world and what context you bring into it.',
+            },
+          ],
+        nextMissingField: accepted
+          ? null
+          : {
+            fieldId: 'participantContextText',
+            label: 'Entry Profile',
+            description: 'A short text describing who you are in this world and what context you bring into it.',
+          },
         missingFieldGuidance: {
-          mode: nextMissingField ? 'ordered_required_fields' : 'complete',
-          orderedMissingFields: missingFields,
-          orderedMissingFieldIds: missingFields.map((field) => field.fieldId),
-          nextMissingField,
-          remainingRequiredFieldCount: missingFields.length,
+          mode: accepted ? 'complete' : 'single_text_field',
+          orderedMissingFields: accepted
+            ? []
+            : [
+              {
+                fieldId: 'participantContextText',
+                label: 'Entry Profile',
+                description: 'A short text describing who you are in this world and what context you bring into it.',
+              },
+            ],
+          orderedMissingFieldIds: accepted ? [] : ['participantContextText'],
+          nextMissingField: accepted
+            ? null
+            : {
+              fieldId: 'participantContextText',
+              label: 'Entry Profile',
+              description: 'A short text describing who you are in this world and what context you bring into it.',
+            },
+          remainingRequiredFieldCount: accepted ? 0 : 1,
         },
-        normalizedProfile,
-        nextAction:
-          missingFields.length === 0 ? 'call_join_world' : 'retry_join_world_after_profile_update',
-      };
-
-      const worldDetail = worldService.describeWorldDetail(world.worldId);
-      return {
-        ...joinCheck,
-        profileCollectionFlow: buildWorldProfileCollectionFlow({
-          worldDetail,
-          joinCheck,
-          profile: normalizedProfile,
-          maxFieldsPerStep,
-        }),
+        nextAction: accepted ? 'call_join_world' : 'retry_join_world_after_profile_update',
       };
     },
-    async createMembership({ worldId, agentId, profileSnapshot } = {}) {
-      worldService.requireWorld(worldId);
+
+    async createMembership({ worldId, agentId, participantContextText } = {}) {
+      const world = worldService.requireWorld(worldId);
       const membershipStore = assertStore();
       const normalizedAgentId = normalizeAgentId(agentId);
-      if (!normalizedAgentId) {
-        throw createInvalidJoinRequestError('agentId');
-      }
+      if (!normalizedAgentId) throw createInvalidJoinRequestError('agentId');
 
       const agent = membershipStore.getAgent(normalizedAgentId);
+      if (!agent) throw createAgentNotFoundError(normalizedAgentId);
 
-      if (!agent) {
-        throw createAgentNotFoundError(normalizedAgentId);
-      }
-
-      const normalizedProfileSnapshot = normalizeProfileSnapshot(profileSnapshot, agent.profile);
-      const joinCheck = this.evaluateJoin({
-        worldId,
-        profile: normalizedProfileSnapshot,
+      const normalizedParticipantContextText = resolveNormalizedParticipantContextText({
+        world,
+        agent,
+        participantContextText,
       });
-
-      if (!joinCheck.accepted) {
-        throw createMembershipNotEligibleError(joinCheck);
+      if (!normalizedParticipantContextText) {
+        throw createInvalidJoinRequestError(
+          'participantContextText',
+          'participantContextText is required',
+        );
       }
 
       const existingMembership = membershipStore.listMemberships({
@@ -195,34 +166,37 @@ export function createMembershipService({ worldService, store = null } = {}) {
         worldId,
         agentId: normalizedAgentId,
         status: 'joined',
-        profileSnapshot: joinCheck.normalizedProfile,
+        profileSnapshot: normalizeProfileSnapshot(null, normalizedParticipantContextText),
+        participantContextText: normalizedParticipantContextText,
       });
 
       return { membership, created: true };
     },
-    async joinWorld({ worldId, agentId, profile, profileSnapshot, maxFieldsPerStep = 1 } = {}) {
+
+    async joinWorld({
+      worldId,
+      agentId,
+      participantContextText,
+    } = {}) {
       const world = worldService.requireWorld(worldId);
       const membershipStore = assertStore();
       const normalizedAgentId = normalizeAgentId(agentId);
 
-      if (!normalizedAgentId) {
-        throw createInvalidJoinRequestError('agentId');
-      }
+      if (!normalizedAgentId) throw createInvalidJoinRequestError('agentId');
 
       const agent = membershipStore.getAgent(normalizedAgentId);
-      if (!agent) {
-        throw createAgentNotFoundError(normalizedAgentId);
-      }
+      if (!agent) throw createAgentNotFoundError(normalizedAgentId);
 
-      const effectiveProfile = normalizeProfileSnapshot(profile, profileSnapshot, agent.profile);
-      const joinCheck = this.evaluateJoin({
-        worldId: world.worldId,
-        profile: effectiveProfile,
-        maxFieldsPerStep,
+      const normalizedParticipantContextText = resolveNormalizedParticipantContextText({
+        world,
+        agent,
+        participantContextText,
       });
-
-      if (!joinCheck.accepted) {
-        throw createJoinNotEligibleError(joinCheck);
+      if (!normalizedParticipantContextText) {
+        throw createInvalidJoinRequestError(
+          'participantContextText',
+          'participantContextText is required',
+        );
       }
 
       const existingMembership = membershipStore.listMemberships({
@@ -233,49 +207,53 @@ export function createMembershipService({ worldService, store = null } = {}) {
       const membership = existingMembership
         ? await membershipStore.updateMembership(existingMembership.membershipId, {
           status: 'active',
-          profileSnapshot: joinCheck.normalizedProfile,
+          profileSnapshot: normalizeProfileSnapshot(existingMembership.profileSnapshot, normalizedParticipantContextText),
+          participantContextText: normalizedParticipantContextText,
         })
         : await membershipStore.createMembership({
           worldId: world.worldId,
           agentId: normalizedAgentId,
           status: 'active',
-          profileSnapshot: joinCheck.normalizedProfile,
+          profileSnapshot: normalizeProfileSnapshot(null, normalizedParticipantContextText),
+          participantContextText: normalizedParticipantContextText,
         });
 
-      return {
+      const joinResult = {
         status: 'joined',
         worldId: world.worldId,
         membership,
         membershipStatus: membership.status,
         created: !existingMembership,
-        normalizedProfile: joinCheck.normalizedProfile,
+        participantContextText: normalizedParticipantContextText,
         nextAction: 'review_candidate_feed',
-        nextStageSummary: buildNextStageSummary(world),
-        orchestration: buildWorldJoinOutcomeOrchestration({
-          worldDetail: worldService.describeWorldDetail(world.worldId),
-          joinResult: {
-            membershipStatus: membership.status,
-            membership,
-            normalizedProfile: joinCheck.normalizedProfile,
-            nextAction: 'review_candidate_feed',
-            nextStageSummary: buildNextStageSummary(world),
-          },
-        }),
+        nextStageSummary: buildNextStageSummary(),
+      };
+
+      return {
+        ...joinResult,
+        orchestration: buildResolvedWorldJoinOrchestration({
+          joinResult,
+          candidateDelivery: null,
+        }) || null,
       };
     },
+
     getMembership({ worldId, agentId, includeDisabled = false } = {}) {
       const normalizedAgentId = normalizeAgentId(agentId);
       if (!normalizedAgentId) return null;
       worldService.requireWorld(worldId, { includeDisabled });
       return assertStore().listMemberships({ worldId, agentId: normalizedAgentId })[0] || null;
     },
+
     listMemberships({ worldId, agentId = null, status = null, includeDisabled = false } = {}) {
       worldService.requireWorld(worldId, { includeDisabled });
       return assertStore().listMemberships({ worldId, agentId, status });
     },
+
     listMembershipsAcrossWorlds({ agentId = null, status = null } = {}) {
       return assertStore().listMemberships({ agentId, status });
     },
+
     countMemberships({ worldId, agentId = null, status = null, includeDisabled = false } = {}) {
       worldService.requireWorld(worldId, { includeDisabled });
       return assertStore().countMemberships({ worldId, agentId, status });

package/src/product-shell/onboarding/onboarding-service.js

@@ -9,7 +9,7 @@ import {
 
 const DEFAULT_INSTALL_CHANNEL_ID = 'claworld';
 const DEFAULT_INSTALL_ACCOUNT_ID = 'claworld';
-const DEFAULT_INSTALL_LOCAL_AGENT_ID = 'claworld';
+const DEFAULT_INSTALL_LOCAL_AGENT_ID = 'main';
 const DEFAULT_ACTIVATION_DISPLAY_NAME = 'Claworld Agent';
 
 function normalizeText(value, fallback = null) {
@@ -174,7 +174,7 @@ export function createOnboardingService({ worldService, store = null } = {}) {
           `run ${CLAWORLD_INSTALLER_COMMAND}`,
           'installer validates OpenClaw availability and minimum host version',
           'installer verifies or installs the claworld OpenClaw plugin package',
-          'installer writes or refreshes the managed claworld channel config',
+          'installer writes or refreshes the managed claworld channel config and binds it to the local main agent by default',
           'installer calls POST /v1/onboarding/activate to obtain agentId and appToken when reuse is not possible',
           'installer persists the returned appToken into the managed claworld account config',
           'installer reloads or starts the runtime and verifies the relay binding',

package/src/product-shell/orchestration/world-conversation-orchestrator.js

@@ -0,0 +1,30 @@
+import { createSystemMessageOrchestrator } from './world-conversation-text.js';
+
+export function createWorldConversationOrchestrator({
+  worldService,
+  resultService,
+  systemMessages = createSystemMessageOrchestrator(),
+} = {}) {
+  return {
+    previewConversation({ worldId, conversationKey = 'cnv_preview' } = {}) {
+      const world = worldService.requireWorld(worldId);
+      const openingPlan = systemMessages.planMessages({
+        conversationId: conversationKey,
+        trigger: 'conversation_started',
+        worldRules: world.conversationTemplate.worldRules,
+      });
+      const convergencePlan = [];
+
+      return {
+        worldId: world.worldId,
+        conversationTemplate: {
+          mode: world.conversationTemplate.mode,
+        },
+        openingPlan,
+        convergencePlan,
+        resultPreview: resultService.previewConversation({ world, conversationKey }),
+        status: 'preview_ready',
+      };
+    },
+  };
+}