@xfxstudio/claworld 0.1.0

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

@@ -0,0 +1,230 @@
+import { randomUUID } from 'crypto';
+import {
+  CLAWORLD_DOCTOR_COMMAND,
+  CLAWORLD_INSTALLER_COMMAND,
+  CLAWORLD_INSTALLER_PACKAGE_NAME,
+  CLAWORLD_OPENCLAW_MIN_HOST_VERSION,
+  CLAWORLD_UPDATE_COMMAND,
+} from '../../openclaw/installer/constants.js';
+
+const DEFAULT_INSTALL_CHANNEL_ID = 'claworld';
+const DEFAULT_INSTALL_ACCOUNT_ID = 'claworld';
+const DEFAULT_INSTALL_LOCAL_AGENT_ID = 'claworld';
+const DEFAULT_ACTIVATION_DISPLAY_NAME = 'Claworld Agent';
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function projectRecommendedWorld(world = {}) {
+  return {
+    worldId: world.worldId,
+    displayName: world.displayName,
+    summary: world.summary,
+    category: world.category,
+  };
+}
+
+function createConfigurationError() {
+  const error = new Error('onboarding_store_unavailable');
+  error.code = 'onboarding_store_unavailable';
+  error.status = 500;
+  error.responseBody = {
+    error: error.code,
+    message: 'onboarding activation requires a configured metadata store',
+  };
+  return error;
+}
+
+function createInvalidActivationRequestError(fieldId, message) {
+  const error = new Error(`invalid_onboarding_activation:${fieldId}`);
+  error.code = 'invalid_onboarding_activation';
+  error.status = 400;
+  error.responseBody = {
+    error: error.code,
+    message: 'dialog-first onboarding activation only accepts backend-issued identity flow inputs',
+    fieldErrors: [
+      {
+        fieldId,
+        message,
+      },
+    ],
+  };
+  return error;
+}
+
+function createHiddenActivationAgentCode() {
+  return `claworld_install_${randomUUID().replace(/-/g, '').slice(0, 20)}`;
+}
+
+function createActivatedResponse({ agent, appToken, created, bindingSource }) {
+  return {
+    status: 'activated',
+    created: created === true,
+    bindingSource: normalizeText(bindingSource, null),
+    agentId: normalizeText(agent?.agentId, null),
+    appToken: normalizeText(appToken, null),
+    agentCode: null,
+  };
+}
+
+function validateActivationInput(input = {}) {
+  const normalizedInput = input && typeof input === 'object' && !Array.isArray(input) ? input : {};
+  const blockedFields = [
+    ['agentId', 'dialog-first activation must not receive a user-provided agentId'],
+    ['agentCode', 'dialog-first activation must not receive a user-provided agentCode'],
+    ['code', 'dialog-first activation must not receive a user-provided code'],
+    ['appToken', 'dialog-first activation must not receive a user-provided appToken in the request body'],
+  ];
+
+  for (const [fieldId, message] of blockedFields) {
+    if (normalizeText(normalizedInput[fieldId], null)) {
+      throw createInvalidActivationRequestError(fieldId, message);
+    }
+  }
+
+  return {
+    displayName: normalizeText(normalizedInput.displayName, DEFAULT_ACTIVATION_DISPLAY_NAME),
+  };
+}
+
+function createActivatedAgent({ store, displayName }) {
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    try {
+      return store.createAgent({
+        agentCode: createHiddenActivationAgentCode(),
+        displayName,
+      });
+    } catch (error) {
+      if (error?.message === 'address already exists') continue;
+      throw error;
+    }
+  }
+
+  throw new Error('failed_to_generate_activation_identity');
+}
+
+export function createOnboardingService({ worldService, store = null } = {}) {
+  function assertStore() {
+    if (!store) throw createConfigurationError();
+    return store;
+  }
+
+  return {
+    getInstallManifest() {
+      const recommendedWorlds = worldService.listWorlds().slice(0, 3).map((world) => projectRecommendedWorld(world));
+      return {
+        product: 'claworld',
+        mode: 'agent_install',
+        installer: {
+          command: CLAWORLD_INSTALLER_COMMAND,
+          packageName: CLAWORLD_INSTALLER_PACKAGE_NAME,
+          minHostVersion: CLAWORLD_OPENCLAW_MIN_HOST_VERSION,
+          canonicalFlow: 'installer_first',
+          lifecycle: {
+            install: CLAWORLD_INSTALLER_COMMAND,
+            doctor: CLAWORLD_DOCTOR_COMMAND,
+            update: CLAWORLD_UPDATE_COMMAND,
+          },
+        },
+        plugin: {
+          pluginId: DEFAULT_INSTALL_CHANNEL_ID,
+          packageName: CLAWORLD_INSTALLER_PACKAGE_NAME,
+          installMode: 'npm',
+          minHostVersion: CLAWORLD_OPENCLAW_MIN_HOST_VERSION,
+        },
+        setup: {
+          channelId: DEFAULT_INSTALL_CHANNEL_ID,
+          defaultAccountId: DEFAULT_INSTALL_ACCOUNT_ID,
+          defaultLocalAgentId: DEFAULT_INSTALL_LOCAL_AGENT_ID,
+          configPath: 'channels.claworld.accounts.<accountId>',
+          credentialField: 'appToken',
+          managedBy: 'host_agent_or_openclaw_runtime',
+          userInput: {
+            requiresCode: false,
+            requiresAgentId: false,
+            requiresToken: false,
+          },
+        },
+        compatibility: {
+          nativeOpenclaw: {
+            status: 'compatibility_only',
+            commands: [
+              'openclaw onboard',
+              'openclaw channels add claworld --app-token <token>',
+            ],
+          },
+        },
+        activation: {
+          endpoint: '/v1/onboarding/activate',
+          method: 'POST',
+          requiresUserCode: false,
+          canonicalIdentityField: 'agentId',
+          credentialField: 'appToken',
+          responseFields: ['status', 'agentId', 'appToken', 'agentCode'],
+        },
+        verification: {
+          statusRoute: '/plugins/claworld/status',
+          pairTool: 'claworld_pair_agent',
+          expectedBinding: 'runtime_bound_by_app_token',
+        },
+        steps: [
+          `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 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',
+          `ongoing lifecycle uses ${CLAWORLD_UPDATE_COMMAND} for tracked package updates plus managed repair, then ${CLAWORLD_DOCTOR_COMMAND} for health confirmation`,
+        ],
+        recommendedWorlds,
+        status: 'ready',
+      };
+    },
+    getFirstRunPlan({ worldId = null } = {}) {
+      const preferredWorld = worldId ? worldService.getWorld(worldId) : null;
+      const fallbackWorld = worldService.getWorld('dating-demo-world');
+      const selectedWorld = preferredWorld || fallbackWorld || worldService.getWorld(worldService.listWorldIds()[0]);
+
+      return {
+        selectedWorld: selectedWorld ? { worldId: selectedWorld.worldId, displayName: selectedWorld.displayName } : null,
+        actions: [
+          'install the claworld plugin and write the managed config shape',
+          'activate the install through POST /v1/onboarding/activate',
+          'persist the returned appToken and verify the runtime binding',
+          'collect required world profile fields',
+          'validate world membership eligibility',
+          'start the first A2A loop or deliver world content',
+        ],
+        status: 'ready',
+      };
+    },
+    activateInstallation({ auth = null, input = {} } = {}) {
+      const activationInput = validateActivationInput(input);
+      assertStore();
+
+      if (auth?.ok) {
+        return createActivatedResponse({
+          agent: auth.agent,
+          appToken: auth.token,
+          created: false,
+          bindingSource: 'provided_app_token',
+        });
+      }
+
+      const createdAgent = createActivatedAgent({
+        store,
+        displayName: activationInput.displayName,
+      });
+      return createActivatedResponse({
+        agent: createdAgent,
+        appToken: createdAgent.bootstrapCredential?.token || null,
+        created: true,
+        bindingSource: 'created_agent_app_token',
+      });
+    },
+  };
+}

package/src/product-shell/orchestration/session-orchestrator.js

@@ -0,0 +1,38 @@
+import { createSystemMessageOrchestrator } from '../../lib/runtime-guidance.js';
+
+export function createSessionOrchestrator({
+  worldService,
+  resultService,
+  systemMessages = createSystemMessageOrchestrator(),
+} = {}) {
+  return {
+    previewSession({ worldId, sessionId = 'ses_preview' } = {}) {
+      const world = worldService.requireWorld(worldId);
+      const openingPlan = systemMessages.planMessages({
+        sessionId,
+        trigger: 'session_started',
+        worldRules: world.sessionTemplate.worldRules,
+      });
+      const convergencePlan = systemMessages.planMessages({
+        sessionId,
+        trigger: 'convergence',
+        remainingTurns: Math.max(world.sessionTemplate.maxTurns - 1, 0),
+        worldRules: world.sessionTemplate.worldRules,
+      });
+
+      return {
+        worldId: world.worldId,
+        sessionTemplate: {
+          mode: world.sessionTemplate.mode,
+          maxTurns: world.sessionTemplate.maxTurns,
+          turnTimeoutMs: world.sessionTemplate.turnTimeoutMs,
+          raiseHandPolicy: world.sessionTemplate.raiseHandPolicy,
+        },
+        openingPlan,
+        convergencePlan,
+        resultPreview: resultService.preview({ world, sessionId }),
+        status: 'preview_ready',
+      };
+    },
+  };
+}

package/src/product-shell/results/result-service.js

@@ -0,0 +1,15 @@
+import { createCanonicalResultBuilder } from '../../openclaw/runtime/canonical-result-builder.js';
+
+export function createResultService({ builder = createCanonicalResultBuilder() } = {}) {
+  return {
+    schema: builder.schema,
+    preview({ world, sessionId = 'ses_preview' } = {}) {
+      return builder.build({
+        sessionId,
+        intentSignals: world.resultContract.exampleSignals.intentSignals,
+        conversationSignals: world.resultContract.exampleSignals.conversationSignals,
+        agentSignals: world.resultContract.exampleSignals.agentSignals,
+      });
+    },
+  };
+}

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

@@ -0,0 +1,359 @@
+import { projectSearchModel } from '../contracts/world-manifest.js';
+import { WORLD_ACTIONS } from '../worlds/world-authorization.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 normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function normalizeAgentId(agentId) {
+  return normalizeText(agentId, null);
+}
+
+function normalizeInteger(value, fallback = 0) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(0, Math.trunc(parsed));
+}
+
+function normalizeStringList(value) {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(
+    value
+      .map((entry) => normalizeText(entry, null)?.toLowerCase() || null)
+      .filter(Boolean),
+  )];
+}
+
+function normalizeComparableText(value) {
+  return normalizeText(value, null)?.toLowerCase() || null;
+}
+
+function normalizeSearchLimit(limit, fallback = 10) {
+  const normalized = normalizeInteger(limit, fallback);
+  if (normalized <= 0) return fallback;
+  return Math.min(normalized, 25);
+}
+
+function createConfigurationError() {
+  const error = new Error('membership_store_unavailable');
+  error.code = 'membership_store_unavailable';
+  error.status = 500;
+  return error;
+}
+
+function createInvalidSearchRequestError(fieldId, message = `${fieldId} is required`) {
+  const error = new Error(`invalid_search_request:${fieldId}`);
+  error.code = 'invalid_search_request';
+  error.status = 400;
+  error.responseBody = {
+    error: error.code,
+    message: 'world search request is missing required fields',
+    fieldErrors: [
+      {
+        fieldId,
+        message,
+      },
+    ],
+  };
+  return error;
+}
+
+function createAgentNotFoundError(agentId) {
+  const error = new Error(`agent_not_found:${agentId}`);
+  error.code = 'agent_not_found';
+  error.status = 404;
+  return error;
+}
+
+function createSearchMembershipNotActiveError(worldId, agentId) {
+  const error = new Error(`world_search_membership_not_active:${worldId}:${agentId}`);
+  error.code = 'world_search_membership_not_active';
+  error.status = 409;
+  error.responseBody = {
+    error: error.code,
+    message: 'agent must have an active world membership before searching the world',
+    worldId,
+    agentId,
+    requiredMembershipStatus: 'active',
+  };
+  return error;
+}
+
+function normalizeQuery(world, query = {}, viewerProfile = {}) {
+  const baseProfile = viewerProfile && typeof viewerProfile === 'object' ? viewerProfile : {};
+  const overrides = query && typeof query === 'object' ? query : {};
+
+  return Object.fromEntries(
+    world.searchSchema.inputFields
+      .map((field) => {
+        const hasOverride = Object.prototype.hasOwnProperty.call(overrides, field.fieldId);
+        const value = hasOverride ? overrides[field.fieldId] : baseProfile[field.fieldId];
+        return [field.fieldId, value];
+      })
+      .filter(([, value]) => !isEmptyValue(value)),
+  );
+}
+
+function resolveFieldWeight(worldId, field) {
+  const fieldId = field.fieldId;
+  if (worldId === 'dating-demo-world') {
+    if (fieldId === 'intent') return { exact: 50, overlapUnit: 10, overlapCap: 20 };
+    if (fieldId === 'location') return { exact: 30, overlapUnit: 10, overlapCap: 20 };
+    if (fieldId === 'interests') return { exact: 20, overlapUnit: 10, overlapCap: 20 };
+  }
+  if (worldId === 'skill-handoff-world') {
+    if (fieldId === 'capabilities') return { exact: 50, overlapUnit: 10, overlapCap: 50 };
+    if (fieldId === 'budgetBand') return { exact: 20, overlapUnit: 10, overlapCap: 20 };
+  }
+  if (worldId === 'job-match-world') {
+    if (fieldId === 'targetRole') return { exact: 50, overlapUnit: 10, overlapCap: 20 };
+    if (fieldId === 'location') return { exact: 15, overlapUnit: 10, overlapCap: 20 };
+    if (fieldId === 'workMode') return { exact: 15, overlapUnit: 10, overlapCap: 20 };
+    if (fieldId === 'experienceSummary') return { exact: 20, overlapUnit: 10, overlapCap: 20 };
+  }
+
+  return {
+    exact: field.required ? 30 : 15,
+    overlapUnit: field.required ? 10 : 6,
+    overlapCap: field.required ? 20 : 12,
+  };
+}
+
+function compareField(field, queryValue, candidateValue, worldId) {
+  if (isEmptyValue(queryValue) || isEmptyValue(candidateValue)) return null;
+
+  const weights = resolveFieldWeight(worldId, field);
+
+  if (field.type === 'string[]') {
+    const queryItems = normalizeStringList(queryValue);
+    const candidateItems = normalizeStringList(candidateValue);
+    const sharedValues = queryItems.filter((entry) => candidateItems.includes(entry));
+    if (sharedValues.length === 0) return null;
+
+    return {
+      fieldId: field.fieldId,
+      label: field.label,
+      matchType: 'overlap',
+      queryValue: queryItems,
+      candidateValue: candidateItems,
+      sharedValues,
+      contribution: Math.min(sharedValues.length * weights.overlapUnit, weights.overlapCap),
+    };
+  }
+
+  const normalizedQueryValue = normalizeComparableText(queryValue);
+  const normalizedCandidateValue = normalizeComparableText(candidateValue);
+  if (!normalizedQueryValue || !normalizedCandidateValue) return null;
+  if (normalizedQueryValue !== normalizedCandidateValue) return null;
+
+  return {
+    fieldId: field.fieldId,
+    label: field.label,
+    matchType: 'exact',
+    queryValue: normalizeText(queryValue, ''),
+    candidateValue: normalizeText(candidateValue, ''),
+    sharedValues: [],
+    contribution: weights.exact,
+  };
+}
+
+function projectSummaryField(field, profile = {}) {
+  const value = profile[field.fieldId];
+  if (isEmptyValue(value)) return null;
+
+  return {
+    fieldId: field.fieldId,
+    label: field.label,
+    value: Array.isArray(value) ? value : normalizeText(value, null),
+  };
+}
+
+function projectProfileSummary(world, profile = {}, agent = null) {
+  return {
+    displayName: normalizeText(agent?.displayName, null),
+    headline: normalizeText(profile.headline, null),
+    requiredFields: world.joinSchema.requiredFields
+      .map((field) => projectSummaryField(field, profile))
+      .filter(Boolean),
+    optionalFields: world.joinSchema.optionalFields
+      .map((field) => projectSummaryField(field, profile))
+      .filter(Boolean),
+  };
+}
+
+function resolveSearchResultAgentId(item = {}, fallback = null) {
+  return normalizeText(item.agentId, normalizeText(item.playerId, fallback));
+}
+
+function compareSearchResults(left, right) {
+  if (right.score !== left.score) return right.score - left.score;
+  if (right.matchedFieldIds.length !== left.matchedFieldIds.length) {
+    return right.matchedFieldIds.length - left.matchedFieldIds.length;
+  }
+  if (left.joinedAt !== right.joinedAt) {
+    return String(left.joinedAt).localeCompare(String(right.joinedAt));
+  }
+  return String(resolveSearchResultAgentId(left, '')).localeCompare(String(resolveSearchResultAgentId(right, '')));
+}
+
+function compareRecentFallbackResults(left, right) {
+  if (left.lastHeartbeatAt !== right.lastHeartbeatAt) {
+    return String(right.lastHeartbeatAt || '').localeCompare(String(left.lastHeartbeatAt || ''));
+  }
+  if (left.joinedAt !== right.joinedAt) {
+    return String(right.joinedAt || '').localeCompare(String(left.joinedAt || ''));
+  }
+  return String(resolveSearchResultAgentId(left, '')).localeCompare(String(resolveSearchResultAgentId(right, '')));
+}
+
+function summarizeMatchedFields(matchedFields = []) {
+  if (matchedFields.length === 0) {
+    return 'Recently active online world member with no direct profile overlap in the current query.';
+  }
+
+  return `Matched on ${matchedFields.map((field) => field.label).join(', ')}.`;
+}
+
+export function createWorldSearchService({
+  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);
+  }
+
+  function buildViewerContext(world, membershipStore, normalizedAgentId) {
+    const viewerAgent = membershipStore.getAgent(normalizedAgentId);
+    if (!viewerAgent) {
+      throw createAgentNotFoundError(normalizedAgentId);
+    }
+
+    const authorization = worldAuthorizationService.evaluateWorldAction({
+      worldId: world.worldId,
+      actorAgentId: normalizedAgentId,
+      action: WORLD_ACTIONS.SEARCH,
+    });
+
+    if (!authorization.allowed || authorization.membership?.status !== 'active') {
+      throw createSearchMembershipNotActiveError(world.worldId, normalizedAgentId);
+    }
+
+    return {
+      viewerAgent,
+      viewerMembership: authorization.membership,
+    };
+  }
+
+  return {
+    describeSearch(worldId) {
+      const world = worldService.requireWorld(worldId);
+      return projectSearchModel(world);
+    },
+    searchWorld({ worldId, agentId, query = {}, limit = null } = {}) {
+      const world = worldService.requireWorld(worldId);
+      const membershipStore = assertStore();
+      const normalizedAgentId = normalizeAgentId(agentId);
+      if (!normalizedAgentId) {
+        throw createInvalidSearchRequestError('agentId');
+      }
+
+      const { viewerAgent, viewerMembership } = buildViewerContext(world, membershipStore, normalizedAgentId);
+      const searchInput = normalizeQuery(world, query, viewerMembership.profileSnapshot || viewerAgent.profile || {});
+      const normalizedLimit = normalizeSearchLimit(limit, world.searchSchema.defaultLimit);
+      const onlineOnly = world.searchSchema.onlineOnly;
+      const activeMemberships = membershipStore.listMemberships({
+        worldId: world.worldId,
+        status: 'active',
+      });
+
+      const items = activeMemberships
+        .filter((membership) => membership.agentId !== normalizedAgentId)
+        .map((membership) => {
+          const candidateAgent = membershipStore.getAgent(membership.agentId);
+          if (!candidateAgent) return null;
+
+          const presenceState = resolvePresence(candidateAgent.agentId);
+          if (onlineOnly && presenceState.online !== true) return null;
+
+          const matchedFields = world.searchSchema.inputFields
+            .map((field) => compareField(
+              field,
+              searchInput[field.fieldId],
+              membership.profileSnapshot?.[field.fieldId],
+              world.worldId,
+            ))
+            .filter(Boolean);
+
+          return {
+            agentId: candidateAgent.agentId,
+            playerId: candidateAgent.agentId,
+            membershipId: membership.membershipId,
+            worldId: world.worldId,
+            displayName: normalizeText(candidateAgent.displayName, candidateAgent.agentCode),
+            headline: normalizeText(membership.profileSnapshot?.headline, null),
+            address: candidateAgent.address,
+            online: presenceState.online === true,
+            connectedAt: presenceState.connectedAt,
+            lastHeartbeatAt: presenceState.lastHeartbeatAt,
+            score: matchedFields.reduce((sum, field) => sum + field.contribution, 0),
+            matchedFieldIds: matchedFields.map((field) => field.fieldId),
+            matchedFields,
+            resultType: matchedFields.length > 0 ? 'matched' : 'fallback',
+            reasonSummary: summarizeMatchedFields(matchedFields),
+            joinedAt: membership.joinedAt,
+            profileSummary: projectProfileSummary(world, membership.profileSnapshot || {}, candidateAgent),
+          };
+        })
+        .filter(Boolean);
+
+      const matchedItems = items
+        .filter((item) => item.resultType === 'matched')
+        .sort(compareSearchResults);
+      const fallbackItems = items
+        .filter((item) => item.resultType === 'fallback')
+        .sort(compareRecentFallbackResults);
+      const orderedItems = [...matchedItems, ...fallbackItems];
+
+      return {
+        worldId: world.worldId,
+        agentId: normalizedAgentId,
+        viewerMembershipId: viewerMembership.membershipId,
+        searchModel: projectSearchModel(world),
+        searchInput,
+        onlineOnly,
+        candidateSource: onlineOnly ? 'active_memberships_online' : 'active_memberships',
+        limit: normalizedLimit,
+        totalMatches: orderedItems.length,
+        items: orderedItems.slice(0, normalizedLimit),
+        nextAction: orderedItems.length > 0 ? 'select_player_and_start_conversation' : 'broaden_search_or_wait',
+        status: orderedItems.length > 0 ? 'search_ready' : 'no_matches',
+      };
+    },
+    searchPlayers(options = {}) {
+      return this.searchWorld(options);
+    },
+  };
+}