@xfxstudio/claworld 0.2.24 → 2026.4.14-testing.1

package/src/openclaw/plugin/relay-client.js

@@ -2,6 +2,7 @@ import { EventEmitter } from 'events';
 import WebSocket from 'ws';
 import { resolveClaworldRuntimeConfig } from './config-schema.js';
 import { buildRuntimeAuthHeaders } from './account-identity.js';
+import { buildClaworldRelayClientVersion } from '../plugin-version.js';
 import { createRelayEventProtocol } from '../protocol/relay-event-protocol.js';
 import { createInboundSessionRouter } from '../runtime/inbound-session-router.js';
 import { createOutboundSessionBridge } from '../runtime/outbound-session-bridge.js';
@@ -486,7 +487,7 @@ export class ClaworldRelayClient extends EventEmitter {
     config,
     agentId,
     credential = null,
-    clientVersion = 'claworld-plugin/0.2.24',
+    clientVersion = buildClaworldRelayClientVersion(),
     sessionTarget,
     fallbackTarget,
   } = {}) {

package/src/openclaw/plugin-version.js

@@ -0,0 +1,67 @@
+import { readFileSync } from 'node:fs';
+import repoPackageJson from '../../package.json' with { type: 'json' };
+
+export const CLAWORLD_PLUGIN_PACKAGE_NAME = '@xfxstudio/claworld';
+export const CLAWORLD_PLUGIN_VERSION_HEADER = 'x-claworld-plugin-version';
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function normalizeHeaderValue(value) {
+  if (Array.isArray(value)) {
+    return normalizeHeaderValue(value[0]);
+  }
+  const normalized = normalizeText(value, null);
+  if (!normalized) return null;
+  return normalized.split(',')[0]?.trim() || null;
+}
+
+export function normalizeClaworldPluginVersion(value, fallback = null) {
+  const normalized = normalizeText(value, null);
+  if (!normalized) return fallback;
+  const withoutPrefix = normalized.replace(/^v/i, '');
+  if (!/^\d+(?:\.\d+)*(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(withoutPrefix)) {
+    return fallback;
+  }
+  return withoutPrefix;
+}
+
+function resolveCurrentPluginVersion() {
+  const repoVersion = normalizeClaworldPluginVersion(repoPackageJson?.version, null);
+  if (repoPackageJson?.name === CLAWORLD_PLUGIN_PACKAGE_NAME && repoVersion) {
+    return repoVersion;
+  }
+
+  try {
+    const publishSurfaceSource = readFileSync(
+      new URL('../../packages/openclaw-plugin/package.json', import.meta.url),
+      'utf8',
+    );
+    const publishSurfacePackageJson = JSON.parse(publishSurfaceSource);
+    const publishSurfaceVersion = normalizeClaworldPluginVersion(publishSurfacePackageJson?.version, null);
+    if (publishSurfacePackageJson?.name === CLAWORLD_PLUGIN_PACKAGE_NAME && publishSurfaceVersion) {
+      return publishSurfaceVersion;
+    }
+  } catch {}
+
+  return repoVersion || '0.0.0';
+}
+
+export const CLAWORLD_PLUGIN_CURRENT_VERSION = resolveCurrentPluginVersion();
+
+export function readClaworldPluginVersionFromHeaders(headers = {}) {
+  const rawVersion = normalizeHeaderValue(headers?.[CLAWORLD_PLUGIN_VERSION_HEADER]);
+  return {
+    rawVersion,
+    reportedVersion: normalizeClaworldPluginVersion(rawVersion, rawVersion),
+    normalizedVersion: normalizeClaworldPluginVersion(rawVersion, null),
+    source: rawVersion ? CLAWORLD_PLUGIN_VERSION_HEADER : null,
+  };
+}
+
+export function buildClaworldRelayClientVersion(version = CLAWORLD_PLUGIN_CURRENT_VERSION) {
+  return `claworld-plugin/${normalizeClaworldPluginVersion(version, CLAWORLD_PLUGIN_CURRENT_VERSION)}`;
+}

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

@@ -1,4 +1,5 @@
 import { resolveClaworldRuntimeConfig } from '../plugin/config-schema.js';
+import { buildRuntimeAuthHeaders } from '../plugin/account-identity.js';
 import { createRuntimeBoundaryError } from '../../lib/runtime-errors.js';
 import { extractBackendErrorContext } from './backend-error-context.js';
 import {
@@ -23,6 +24,11 @@ function normalizeStringList(values = []) {
   return [...new Set(values.map((value) => normalizeText(value, null)).filter(Boolean))];
 }
 
+function normalizeWorldRole(worldRole, fallback = null) {
+  const normalized = normalizeText(worldRole, fallback);
+  return ['owner', 'member'].includes(normalized) ? normalized : fallback;
+}
+
 function sentenceCase(value, fallback = '') {
   const normalized = normalizeText(value, fallback);
   if (!normalized) return fallback;
@@ -48,9 +54,18 @@ function normalizeWorldSummary(world = {}) {
   return {
     worldId: normalizeText(rawWorldId, 'unknown-world'),
     displayName: normalizeText(summary.displayName || world.displayName, normalizeText(rawWorldId, 'Unknown World')),
+    summary: normalizeText(summary.summary || world.summary, null),
     worldContextText: normalizeText(summary.worldContextText || world.worldContextText, ''),
     hotness: normalizeInteger(summary.hotness || world.hotness || world.activatedMemberCount, 0),
+    activatedMemberCount: normalizeInteger(summary.activatedMemberCount || world.activatedMemberCount || summary.hotness || world.hotness, 0),
+    tags: normalizeStringList(summary.tags || world.tags),
+    matchScore: normalizeInteger(summary.matchScore || world.matchScore, 0),
+    matchedFieldIds: normalizeStringList(summary.matchedFieldIds || world.matchedFieldIds),
+    matchedTerms: normalizeStringList(summary.matchedTerms || world.matchedTerms),
+    reasonSummary: normalizeText(summary.reasonSummary || world.reasonSummary, null),
     requiredFieldCount: normalizeInteger(summary.requiredFieldCount || world.requiredFieldCount, 0),
+    detailAction: world.detailAction && typeof world.detailAction === 'object' ? world.detailAction : null,
+    joinAction: world.joinAction && typeof world.joinAction === 'object' ? world.joinAction : null,
   };
 }
 
@@ -129,6 +144,7 @@ function normalizeWorldDetail(payload = {}) {
       displayName: normalizeText(payload.displayName, normalizedWorldId),
       worldContextText: normalizeText(payload.worldContextText, ''),
       ownerAgentId: normalizeText(payload.ownerAgentId, null),
+      worldRole: normalizeWorldRole(payload.worldRole, null),
       enabled: typeof payload.enabled === 'boolean' ? payload.enabled : null,
       requiredFieldCount: normalizeInteger(payload.requiredFieldCount, requiredFields.length) || requiredFields.length,
       optionalFieldCount: normalizeInteger(payload.optionalFieldCount, optionalFields.length) || optionalFields.length,
@@ -168,6 +184,7 @@ function normalizeWorldDetail(payload = {}) {
     displayName,
     worldContextText: normalizeText(world.worldContextText || payload.worldContextText, ''),
     ownerAgentId: normalizeText(management.ownerAgentId, null),
+    worldRole: normalizeWorldRole(payload.worldRole, null),
     enabled: typeof management.enabled === 'boolean' ? management.enabled : null,
     statusLabel: normalizeText(management.status, null),
     requiredFieldCount: 1,
@@ -220,6 +237,22 @@ function normalizeCandidateProfileSummary(summary = {}) {
   };
 }
 
+function normalizeSearchAction(action = null) {
+  if (!action || typeof action !== 'object' || Array.isArray(action)) return null;
+  const payload = action.payload && typeof action.payload === 'object' && !Array.isArray(action.payload)
+    ? action.payload
+    : {};
+  const payloadTemplate = action.payloadTemplate && typeof action.payloadTemplate === 'object' && !Array.isArray(action.payloadTemplate)
+    ? action.payloadTemplate
+    : {};
+  return {
+    tool: normalizeText(action.tool, null),
+    summary: normalizeText(action.summary, null),
+    payload,
+    payloadTemplate,
+  };
+}
+
 function normalizeCompatibilitySignal(signal = {}, index = 0) {
   return {
     signalId: normalizeText(signal.signalId, `signal_${index + 1}`),
@@ -259,6 +292,7 @@ function normalizeCandidate(candidate = {}, index = 0) {
   return {
     candidateId: normalizeText(candidate.candidateId, `candidate_${index + 1}`),
     worldId: normalizeText(candidate.worldId, 'unknown-world'),
+    worldRole: normalizeWorldRole(candidate.worldRole, null),
     sourceMembershipId: normalizeText(candidate.sourceMembershipId, null),
     online: candidate.online === true,
     displayName,
@@ -314,7 +348,7 @@ function normalizeCandidateFeedResponse(payload = {}, { worldId = null, agentId
   };
 }
 
-function normalizeWorldJoinResponse(payload = {}, { worldId = null, agentId = null } = {}) {
+export function normalizeWorldJoinResponse(payload = {}, { worldId = null, agentId = null } = {}) {
   const membership = payload.membership && typeof payload.membership === 'object' ? payload.membership : null;
   const normalizedWorldId = normalizeText(payload.worldId, worldId || 'unknown-world');
   const normalizedAgentId = normalizeText(payload.agentId || membership?.agentId, agentId || null);
@@ -330,6 +364,7 @@ function normalizeWorldJoinResponse(payload = {}, { worldId = null, agentId = nu
     status: normalizeText(payload.status, membershipStatus === 'active' ? 'joined' : 'accepted'),
     worldId: normalizedWorldId,
     agentId: normalizedAgentId,
+    worldRole: normalizeWorldRole(payload.worldRole, null),
     membershipStatus,
     participantContextText: normalizeText(
       payload.participantContextText,
@@ -388,7 +423,10 @@ export function buildWorldSelectionPrompt(worldDirectory = {}) {
     : null;
 }
 
-export function buildPostSetupWorldDirectory(payload = {}, { accountId = null } = {}) {
+export function buildPostSetupWorldDirectory(payload = {}, {
+  accountId = null,
+  statusMode = 'directory',
+} = {}) {
   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'
@@ -402,23 +440,83 @@ export function buildPostSetupWorldDirectory(payload = {}, { accountId = null }
       totalPages: items.length > 0 ? 1 : 0,
       totalCount: items.length,
     };
+  const mode = normalizeText(payload.mode, 'browse');
   const sort = normalizeText(payload.sort, 'hot');
+  const statusFallback = items.length > 0
+    ? (statusMode === 'search' ? 'search_ready' : 'ready')
+    : 'no_matches';
+  const normalizedStatus = normalizeText(
+    statusMode === 'directory' && mode === 'browse' && payload.status === 'search_ready'
+      ? 'ready'
+      : payload.status,
+    statusFallback,
+  );
 
   return {
-    status: 'ready',
+    status: normalizedStatus,
     source: 'product_shell',
     accountId: normalizeText(accountId, null),
+    mode,
+    query: normalizeText(payload.query, null),
     worldCount: pagination.totalCount,
     recommendedWorldId,
     items,
     pagination,
     sort,
+    nextAction: normalizeText(payload.nextAction, items.length > 0 ? 'inspect_world_detail_or_join_world' : 'broaden_world_search'),
     orchestration: payload.orchestration && typeof payload.orchestration === 'object'
       ? payload.orchestration
       : null,
   };
 }
 
+function normalizeWorldMemberSearchItem(item = {}) {
+  return {
+    membershipId: normalizeText(item.membershipId, null),
+    worldId: normalizeText(item.worldId, null),
+    displayName: normalizeText(item.displayName, null),
+    agentCode: normalizeText(item.agentCode, null)?.toUpperCase() || null,
+    requestChat: item.requestChat && typeof item.requestChat === 'object' && !Array.isArray(item.requestChat)
+      ? item.requestChat
+      : null,
+    headline: normalizeText(item.headline, null),
+    online: item.online === true,
+    score: normalizeInteger(item.score, 0),
+    matchedFieldIds: normalizeStringList(item.matchedFieldIds),
+    reasonSummary: normalizeText(item.reasonSummary, null),
+    joinedAt: normalizeText(item.joinedAt, null),
+    profileSummary: normalizeCandidateProfileSummary(item.profileSummary || {}),
+    worldFeedbackSummary: item.worldFeedbackSummary && typeof item.worldFeedbackSummary === 'object' && !Array.isArray(item.worldFeedbackSummary)
+      ? {
+        likesReceived: normalizeInteger(item.worldFeedbackSummary.likesReceived, 0),
+        dislikesReceived: normalizeInteger(item.worldFeedbackSummary.dislikesReceived, 0),
+      }
+      : {
+        likesReceived: 0,
+        dislikesReceived: 0,
+      },
+  };
+}
+
+export function normalizeWorldMemberSearchResponse(payload = {}, { accountId = null } = {}) {
+  const items = Array.isArray(payload.items)
+    ? payload.items.map((item) => normalizeWorldMemberSearchItem(item))
+    : [];
+
+  return {
+    status: normalizeText(payload.status, items.length > 0 ? 'search_ready' : 'no_matches'),
+    source: 'product_shell',
+    accountId: normalizeText(accountId, null),
+    worldId: normalizeText(payload.worldId, null),
+    query: normalizeText(payload.query, null),
+    sort: normalizeText(payload.sort, 'match'),
+    limit: normalizeInteger(payload.limit, items.length),
+    totalMatches: normalizeInteger(payload.totalMatches, items.length),
+    nextAction: normalizeText(payload.nextAction, items.length > 0 ? 'request_chat_with_selected_candidate' : 'broaden_search_or_refresh_candidate_feed'),
+    items,
+  };
+}
+
 export function resolveWorldSelection(worldDirectory = {}, selection = null) {
   return resolveBackendWorldSelection(worldDirectory, selection);
 }
@@ -512,11 +610,10 @@ export async function fetchWorldDetail({
   const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
   const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
   const detail = await fetchJson(fetchImpl, `${baseUrl}/v1/worlds/${encodeURIComponent(resolvedWorldId)}`, {
-    headers: {
+    headers: buildRuntimeAuthHeaders(resolvedRuntimeConfig, {
       accept: 'application/json',
       ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
-      ...(resolvedRuntimeConfig.relay?.credentialToken ? { authorization: `Bearer ${resolvedRuntimeConfig.relay.credentialToken}` } : {}),
-    },
+    }),
   });
 
   if (!detail.ok) {
@@ -535,6 +632,55 @@ export async function fetchWorldDetail({
   return normalizeWorldDetail(detail.body);
 }
 
+export async function searchWorlds({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  query = null,
+  limit = null,
+  sort = null,
+  page = null,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for claworld product-shell world search helper');
+  }
+
+  const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+  const searchResult = await fetchJson(fetchImpl, `${baseUrl}/v1/worlds/search`, {
+    method: 'POST',
+    headers: buildRuntimeAuthHeaders(resolvedRuntimeConfig, {
+      accept: 'application/json',
+      'content-type': 'application/json',
+      ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+    }),
+    body: JSON.stringify({
+      query: normalizeText(query, null),
+      sort: normalizeText(sort, null),
+      limit: limit == null ? null : normalizeInteger(limit, 0),
+      page: page == null ? null : normalizeInteger(page, 0),
+    }),
+  });
+
+  if (!searchResult.ok) {
+    logger.error?.('[claworld:product-shell] world search failed', {
+      status: searchResult.status,
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      body: searchResult.body,
+    });
+    throw createProductShellHttpError('world_search', searchResult, {
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+    });
+  }
+
+  return buildPostSetupWorldDirectory(searchResult.body, {
+    accountId: resolvedRuntimeConfig.accountId || accountId || null,
+    statusMode: 'search',
+  });
+}
+
 export async function joinWorld({
   cfg = {},
   accountId = null,
@@ -563,12 +709,11 @@ export async function joinWorld({
   const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
   const joinResult = await fetchJson(fetchImpl, `${baseUrl}/v1/worlds/${encodeURIComponent(resolvedWorldId)}/join`, {
     method: 'POST',
-    headers: {
+    headers: buildRuntimeAuthHeaders(resolvedRuntimeConfig, {
       accept: 'application/json',
       'content-type': 'application/json',
       ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
-      ...(resolvedRuntimeConfig.relay?.credentialToken ? { authorization: `Bearer ${resolvedRuntimeConfig.relay.credentialToken}` } : {}),
-    },
+    }),
     body: JSON.stringify({
       agentId: resolvedAgentId,
       participantContextText: normalizeText(participantContextText, null),
@@ -595,6 +740,68 @@ export async function joinWorld({
   });
 }
 
+export async function searchWorldMembers({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  worldId = null,
+  agentId = null,
+  query = null,
+  sort = null,
+  limit = null,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for claworld product-shell member search helper');
+  }
+
+  const resolvedWorldId = normalizeText(worldId, null);
+  if (!resolvedWorldId) {
+    throw new Error('claworld product-shell member search helper requires worldId');
+  }
+
+  const resolvedAgentId = normalizeText(agentId, null);
+  if (!resolvedAgentId) {
+    throw new Error('claworld product-shell member search helper requires agentId');
+  }
+
+  const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+  const searchResult = await fetchJson(fetchImpl, `${baseUrl}/v1/worlds/${encodeURIComponent(resolvedWorldId)}/search`, {
+    method: 'POST',
+    headers: buildRuntimeAuthHeaders(resolvedRuntimeConfig, {
+      accept: 'application/json',
+      'content-type': 'application/json',
+      ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+    }),
+    body: JSON.stringify({
+      agentId: resolvedAgentId,
+      query: normalizeText(query, null),
+      sort: normalizeText(sort, null),
+      limit: limit == null ? null : normalizeInteger(limit, 0),
+    }),
+  });
+
+  if (!searchResult.ok) {
+    logger.error?.('[claworld:product-shell] world member search failed', {
+      status: searchResult.status,
+      worldId: resolvedWorldId,
+      agentId: resolvedAgentId,
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      body: searchResult.body,
+    });
+    throw createProductShellHttpError('world_member_search', searchResult, {
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      worldId: resolvedWorldId,
+    });
+  }
+
+  return normalizeWorldMemberSearchResponse(searchResult.body, {
+    accountId: resolvedRuntimeConfig.accountId || accountId || null,
+  });
+}
+
 export async function fetchWorldCandidateFeed({
   cfg = {},
   accountId = null,
@@ -628,11 +835,10 @@ export async function fetchWorldCandidateFeed({
     requestUrl.searchParams.set('limit', String(normalizedLimit));
   }
   const candidateFeed = await fetchJson(fetchImpl, requestUrl.toString(), {
-    headers: {
+    headers: buildRuntimeAuthHeaders(resolvedRuntimeConfig, {
       accept: 'application/json',
       ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
-      ...(resolvedRuntimeConfig.relay?.credentialToken ? { authorization: `Bearer ${resolvedRuntimeConfig.relay.credentialToken}` } : {}),
-    },
+    }),
   });
 
   if (!candidateFeed.ok) {
@@ -674,11 +880,10 @@ export async function resolveWorldSelectionFlow({
       const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
       const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
       const worlds = await fetchJson(fetchImpl, `${baseUrl}/v1/worlds`, {
-        headers: {
+        headers: buildRuntimeAuthHeaders(resolvedRuntimeConfig, {
           accept: 'application/json',
           ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
-          ...(resolvedRuntimeConfig.relay?.credentialToken ? { authorization: `Bearer ${resolvedRuntimeConfig.relay.credentialToken}` } : {}),
-        },
+        }),
       });
 
       if (!worlds.ok) {