@xfxstudio/claworld 0.2.23 → 0.2.25

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;
@@ -129,6 +135,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 +175,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,
@@ -259,6 +267,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 +323,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 +339,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,
@@ -512,11 +522,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) {
@@ -563,12 +572,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),
@@ -628,11 +636,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 +681,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) {

package/src/openclaw/runtime/tool-contracts.js

@@ -1,3 +1,5 @@
+import { normalizeAcceptedChatKickoffRecord } from '../../lib/relay/kickoff-progress.js';
+
 function normalizeText(value, fallback = null) {
   if (value == null) return fallback;
   const normalized = String(value).trim();
@@ -159,6 +161,7 @@ function projectToolCandidateDeliverySummary(
       candidateId: normalizeText(summary.candidateId, null),
       sourceMembershipId: normalizeText(summary.sourceMembershipId, null),
       displayName: normalizeText(summary.displayName, null),
+      worldRole: projectWorldRole(summary.worldRole, null),
       headline: normalizeText(summary.headline, null),
       online: summary.online === true,
       rank: normalizeOptionalInteger(summary.rank, null),
@@ -229,9 +232,13 @@ export function projectToolWorldDetail(worldDetail = {}) {
       worldDetail.world?.worldContextText,
       worldDetail.worldContextText || '',
     ),
-    ownerAgentId: normalizeText(worldDetail.management?.ownerAgentId, null),
-    enabled: normalizeOptionalBoolean(worldDetail.management?.enabled, null),
-    status: normalizeText(worldDetail.management?.status, null),
+    ownerAgentId: normalizeText(
+      worldDetail.management?.ownerAgentId,
+      normalizeText(worldDetail.ownerAgentId, null),
+    ),
+    worldRole: projectWorldRole(worldDetail.worldRole, null),
+    enabled: normalizeOptionalBoolean(worldDetail.management?.enabled, normalizeOptionalBoolean(worldDetail.enabled, null)),
+    status: normalizeText(worldDetail.management?.status, normalizeText(worldDetail.statusLabel, null)),
     participantContextField: projectParticipantContextField(worldDetail.participantContextField),
   };
 }
@@ -241,6 +248,7 @@ function projectToolCandidateSummary(summary = {}, index = 0) {
     candidateId: normalizeText(summary.candidateId, `candidate_${index + 1}`),
     displayName: normalizeText(summary.displayName, `Candidate ${index + 1}`),
     agentCode: normalizeText(summary.agentCode, null)?.toUpperCase() || null,
+    worldRole: projectWorldRole(summary.worldRole, null),
     headline: normalizeText(summary.headline, null),
     online: summary.online === true,
     rank: normalizeInteger(summary.rank, 0) || null,
@@ -302,6 +310,7 @@ export function projectToolJoinWorldResponse(
     status: joinResult.membershipStatus === 'active' ? 'joined' : 'accepted',
     worldId: joinResult.worldId,
     accountId: normalizeText(accountId, null),
+    worldRole: projectWorldRole(joinResult.worldRole, null),
     membershipStatus: joinResult.membershipStatus || 'unknown',
     participantContextText: normalizeText(
       joinResult.participantContextText,
@@ -327,6 +336,10 @@ export function projectToolCreateWorldResponse(world = {}, { accountId = null }
     status: normalizeText(world.status, null),
     enabled: normalizeOptionalBoolean(world.enabled, null),
     worldRole: projectWorldRole(world.worldRole, null),
+    ownerJoin:
+      world.ownerJoin && typeof world.ownerJoin === 'object'
+        ? projectToolJoinWorldResponse(world.ownerJoin, { accountId })
+        : null,
     schemaVersion: normalizeOptionalInteger(world.schemaVersion, null),
     createdAt: normalizeText(world.createdAt, null),
   };
@@ -371,6 +384,41 @@ export function projectToolManagedWorldResponse(world = {}, { accountId = null }
   };
 }
 
+function projectToolWorldMembershipSummary(membership = {}) {
+  return {
+    membershipId: normalizeText(membership.membershipId, null),
+    worldId: normalizeText(membership.worldId, null),
+    displayName: normalizeText(membership.displayName, null),
+    worldContextText: normalizeText(membership.worldContextText, null),
+    ownerAgentId: normalizeText(membership.ownerAgentId, null),
+    enabled: normalizeOptionalBoolean(membership.enabled, null),
+    worldStatus: normalizeText(membership.worldStatus, null),
+    worldRole: projectWorldRole(membership.worldRole, null),
+    membershipStatus: normalizeText(membership.membershipStatus, null),
+    participantContextText: normalizeText(membership.participantContextText, null),
+    joinedAt: normalizeText(membership.joinedAt, null),
+    updatedAt: normalizeText(membership.updatedAt, null),
+    nextAction: normalizeText(membership.nextAction, null),
+  };
+}
+
+export function projectToolWorldMembershipListResponse(payload = {}, { accountId = null } = {}) {
+  return {
+    accountId: normalizeText(accountId, null),
+    memberships: Array.isArray(payload.items)
+      ? payload.items.map((membership) => projectToolWorldMembershipSummary(membership))
+      : [],
+    nextAction: normalizeText(payload.nextAction, null),
+  };
+}
+
+export function projectToolWorldMembershipResponse(payload = {}, { accountId = null } = {}) {
+  return {
+    accountId: normalizeText(accountId, null),
+    ...projectToolWorldMembershipSummary(payload),
+  };
+}
+
 export function projectToolFeedbackSubmissionResponse(result = {}) {
   const feedback = result.feedback && typeof result.feedback === 'object' ? result.feedback : {};
   const reporter = feedback.reporter && typeof feedback.reporter === 'object' ? feedback.reporter : {};
@@ -437,20 +485,27 @@ function normalizeConversationScopeDetails(input = {}) {
 }
 
 function projectChatRequestKickoff(kickoff = {}) {
-  if (!kickoff || typeof kickoff !== 'object') return null;
+  const normalizedKickoff = normalizeAcceptedChatKickoffRecord(kickoff, { fallbackStatus: 'skipped' });
+  if (!normalizedKickoff) return null;
   return {
-    status: normalizeText(kickoff.status, 'skipped'),
-    deliveredAt: normalizeText(kickoff.deliveredAt, null),
-    senderKickoffDeliveredAt: normalizeText(kickoff.senderKickoffDeliveredAt, normalizeText(kickoff.deliveredAt, null)),
-    openerAcceptedAt: normalizeText(kickoff.openerAcceptedAt, null),
-    openerDeliveredAt: normalizeText(kickoff.openerDeliveredAt, null),
-    liveChatEstablishedAt: normalizeText(kickoff.liveChatEstablishedAt, null),
-    conversationKey: normalizeText(kickoff.conversationKey, null),
-    localSessionKey: normalizeText(kickoff.localSessionKey, normalizeText(kickoff.sessionKey, null)),
-    turnId: normalizeText(kickoff.turnId, null),
-    deliveryId: normalizeText(kickoff.deliveryId, null),
-    created: typeof kickoff.created === 'boolean' ? kickoff.created : null,
-    reason: normalizeText(kickoff.reason, null),
+    status: normalizeText(normalizedKickoff.status, 'skipped'),
+    deliveredAt: normalizeText(normalizedKickoff.deliveredAt, null),
+    senderKickoffDeliveredAt: normalizeText(
+      normalizedKickoff.senderKickoffDeliveredAt,
+      normalizeText(normalizedKickoff.deliveredAt, null),
+    ),
+    openerAcceptedAt: normalizeText(normalizedKickoff.openerAcceptedAt, null),
+    openerDeliveredAt: normalizeText(normalizedKickoff.openerDeliveredAt, null),
+    liveChatEstablishedAt: normalizeText(normalizedKickoff.liveChatEstablishedAt, null),
+    conversationKey: normalizeText(normalizedKickoff.conversationKey, null),
+    localSessionKey: normalizeText(
+      normalizedKickoff.localSessionKey,
+      normalizeText(normalizedKickoff.sessionKey, null),
+    ),
+    turnId: normalizeText(normalizedKickoff.turnId, null),
+    deliveryId: normalizeText(normalizedKickoff.deliveryId, null),
+    created: typeof normalizedKickoff.created === 'boolean' ? normalizedKickoff.created : null,
+    reason: normalizeText(normalizedKickoff.reason, null),
   };
 }
 

package/src/openclaw/runtime/world-membership-helper.js

@@ -0,0 +1,320 @@
+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';
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function normalizeOptionalBoolean(value, fallback = null) {
+  if (typeof value === 'boolean') return value;
+  return fallback;
+}
+
+function normalizeWorldRole(worldRole, fallback = null) {
+  const normalized = normalizeText(worldRole, fallback);
+  return ['owner', 'member'].includes(normalized) ? normalized : fallback;
+}
+
+function normalizeManagedWorldMembership(payload = {}) {
+  return {
+    membershipId: normalizeText(payload.membershipId, null),
+    worldId: normalizeText(payload.worldId, null),
+    displayName: normalizeText(payload.displayName, null),
+    worldContextText: normalizeText(payload.worldContextText, null),
+    ownerAgentId: normalizeText(payload.ownerAgentId, null),
+    enabled: normalizeOptionalBoolean(payload.enabled, null),
+    worldStatus: normalizeText(payload.worldStatus, null),
+    worldRole: normalizeWorldRole(payload.worldRole, null),
+    membershipStatus: normalizeText(payload.membershipStatus, null),
+    participantContextText: normalizeText(payload.participantContextText, null),
+    joinedAt: normalizeText(payload.joinedAt, null),
+    updatedAt: normalizeText(payload.updatedAt, null),
+    nextAction: normalizeText(payload.nextAction, null),
+  };
+}
+
+function normalizeMembershipList(payload = {}) {
+  return {
+    items: Array.isArray(payload.items)
+      ? payload.items.map((item) => normalizeManagedWorldMembership(item))
+      : [],
+    nextAction: normalizeText(payload.nextAction, null),
+  };
+}
+
+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 === 404) return 'input';
+  if (status === 409) return 'conflict';
+  if (status >= 400 && status < 500) return 'input';
+  return 'runtime';
+}
+
+function createWorldMembershipHttpError(action, response, { accountId = null, worldId = null } = {}) {
+  const backendCode = normalizeText(response?.body?.error, null);
+  const backendMessage = normalizeText(response?.body?.message, `claworld world membership ${action} failed`);
+
+  return createRuntimeBoundaryError({
+    code: backendCode || `claworld_world_membership_${action}_failed`,
+    category: inferHttpErrorCategory(response?.status),
+    status: response?.status ?? 500,
+    message: `claworld world membership ${action} failed: ${response?.status ?? 500}`,
+    publicMessage: backendMessage,
+    recoverable: Number(response?.status) >= 400 && Number(response?.status) < 500,
+    context: {
+      action: `world_membership_${action}`,
+      accountId,
+      ...(worldId ? { worldId } : {}),
+      httpStatus: response?.status ?? 500,
+      ...extractBackendErrorContext(response?.body),
+    },
+  });
+}
+
+export async function fetchWorldMemberships({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  agentId = null,
+  status = null,
+  includeInactive = false,
+  includeDisabled = true,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for claworld world membership helper');
+  }
+
+  const resolvedAgentId = normalizeText(agentId, null);
+  if (!resolvedAgentId) {
+    throw new Error('claworld world membership helper requires agentId');
+  }
+
+  const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+  const requestUrl = new URL(`${baseUrl}/v1/world-memberships`);
+  requestUrl.searchParams.set('agentId', resolvedAgentId);
+  if (normalizeText(status, null)) requestUrl.searchParams.set('status', normalizeText(status, null));
+  if (includeInactive) requestUrl.searchParams.set('includeInactive', 'true');
+  requestUrl.searchParams.set('includeDisabled', includeDisabled ? 'true' : 'false');
+  const result = await fetchJson(fetchImpl, requestUrl.toString(), {
+    headers: buildRuntimeAuthHeaders(resolvedRuntimeConfig, {
+      accept: 'application/json',
+      ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+    }),
+  });
+
+  if (!result.ok) {
+    logger.error?.('[claworld:membership] world memberships fetch failed', {
+      status: result.status,
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      body: result.body,
+    });
+    throw createWorldMembershipHttpError('list', result, {
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+    });
+  }
+
+  return normalizeMembershipList(result.body);
+}
+
+export async function fetchWorldMembership({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  agentId = null,
+  worldId = null,
+  includeDisabled = true,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for claworld world membership helper');
+  }
+
+  const resolvedAgentId = normalizeText(agentId, null);
+  if (!resolvedAgentId) {
+    throw new Error('claworld world membership helper requires agentId');
+  }
+  const resolvedWorldId = normalizeText(worldId, null);
+  if (!resolvedWorldId) {
+    throw new Error('claworld world membership helper requires worldId');
+  }
+
+  const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+  const requestUrl = new URL(`${baseUrl}/v1/worlds/${encodeURIComponent(resolvedWorldId)}/membership`);
+  requestUrl.searchParams.set('agentId', resolvedAgentId);
+  requestUrl.searchParams.set('includeDisabled', includeDisabled ? 'true' : 'false');
+  const result = await fetchJson(fetchImpl, requestUrl.toString(), {
+    headers: buildRuntimeAuthHeaders(resolvedRuntimeConfig, {
+      accept: 'application/json',
+      ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+    }),
+  });
+
+  if (!result.ok) {
+    logger.error?.('[claworld:membership] world membership fetch failed', {
+      status: result.status,
+      worldId: resolvedWorldId,
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      body: result.body,
+    });
+    throw createWorldMembershipHttpError('get', result, {
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      worldId: resolvedWorldId,
+    });
+  }
+
+  return normalizeManagedWorldMembership(result.body);
+}
+
+export async function updateWorldMembershipProfile({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  agentId = null,
+  worldId = null,
+  participantContextText = null,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for claworld world membership helper');
+  }
+
+  const resolvedAgentId = normalizeText(agentId, null);
+  if (!resolvedAgentId) {
+    throw new Error('claworld world membership helper requires agentId');
+  }
+  const resolvedWorldId = normalizeText(worldId, null);
+  if (!resolvedWorldId) {
+    throw new Error('claworld world membership helper requires worldId');
+  }
+
+  const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+  const result = await fetchJson(fetchImpl, `${baseUrl}/v1/worlds/${encodeURIComponent(resolvedWorldId)}/membership`, {
+    method: 'PATCH',
+    headers: buildRuntimeAuthHeaders(resolvedRuntimeConfig, {
+      accept: 'application/json',
+      'content-type': 'application/json',
+      ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+    }),
+    body: JSON.stringify({
+      agentId: resolvedAgentId,
+      participantContextText: normalizeText(participantContextText, null),
+    }),
+  });
+
+  if (!result.ok) {
+    logger.error?.('[claworld:membership] world membership profile update failed', {
+      status: result.status,
+      worldId: resolvedWorldId,
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      body: result.body,
+    });
+    throw createWorldMembershipHttpError('update_profile', result, {
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      worldId: resolvedWorldId,
+    });
+  }
+
+  return normalizeManagedWorldMembership(result.body);
+}
+
+export async function leaveWorldMembership({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  agentId = null,
+  worldId = null,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for claworld world membership helper');
+  }
+
+  const resolvedAgentId = normalizeText(agentId, null);
+  if (!resolvedAgentId) {
+    throw new Error('claworld world membership helper requires agentId');
+  }
+  const resolvedWorldId = normalizeText(worldId, null);
+  if (!resolvedWorldId) {
+    throw new Error('claworld world membership helper requires worldId');
+  }
+
+  const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+  const result = await fetchJson(fetchImpl, `${baseUrl}/v1/worlds/${encodeURIComponent(resolvedWorldId)}/membership/leave`, {
+    method: 'POST',
+    headers: buildRuntimeAuthHeaders(resolvedRuntimeConfig, {
+      accept: 'application/json',
+      'content-type': 'application/json',
+      ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+    }),
+    body: JSON.stringify({
+      agentId: resolvedAgentId,
+    }),
+  });
+
+  if (!result.ok) {
+    logger.error?.('[claworld:membership] world membership leave failed', {
+      status: result.status,
+      worldId: resolvedWorldId,
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      body: result.body,
+    });
+    throw createWorldMembershipHttpError('leave', result, {
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      worldId: resolvedWorldId,
+    });
+  }
+
+  return normalizeManagedWorldMembership(result.body);
+}

package/src/openclaw/runtime/world-moderation-helper.js

@@ -2,6 +2,7 @@ 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 { normalizeWorldJoinResponse } from './product-shell-helper.js';
 
 function normalizeText(value, fallback = null) {
   if (value == null) return fallback;
@@ -85,6 +86,20 @@ function normalizeManagedWorld(payload = {}) {
   };
 }
 
+function normalizeCreatedWorld(payload = {}) {
+  const world = normalizeManagedWorld(payload);
+  return {
+    ...world,
+    ownerJoin:
+      payload.ownerJoin && typeof payload.ownerJoin === 'object'
+        ? normalizeWorldJoinResponse(payload.ownerJoin, {
+          worldId: world.worldId,
+          agentId: world.ownerAgentId,
+        })
+        : null,
+  };
+}
+
 function normalizeOwnedWorldSummary(payload = {}) {
   return {
     worldId: normalizeText(payload.worldId, null),
@@ -174,6 +189,7 @@ export async function createModeratedWorld({
   agentId = null,
   displayName = null,
   worldContextText = null,
+  participantContextText = null,
   enabled = true,
   fetchImpl,
   logger = console,
@@ -200,6 +216,7 @@ export async function createModeratedWorld({
       agentId: resolvedAgentId,
       displayName,
       worldContextText,
+      participantContextText: normalizeText(participantContextText, null),
       enabled,
     }),
   });
@@ -215,7 +232,7 @@ export async function createModeratedWorld({
     });
   }
 
-  return normalizeManagedWorld(created.body);
+  return normalizeCreatedWorld(created.body);
 }
 
 export async function fetchOwnedWorlds({

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

@@ -259,6 +259,11 @@ function normalizeDeliveryReason(reason = {}) {
   };
 }
 
+function normalizeWorldRole(worldRole, fallback = null) {
+  const normalized = normalizeText(worldRole, fallback);
+  return ['owner', 'member'].includes(normalized) ? normalized : fallback;
+}
+
 function normalizeCandidate(candidate = {}, index = 0) {
   const normalizedRank = normalizeNumber(candidate.rank, null);
   const displayName = normalizeText(
@@ -280,6 +285,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,
@@ -622,6 +628,7 @@ export function buildCandidateDeliverySummary(candidateFeed = {}, { worldDetail
       .filter(Boolean);
     const deliveryReasonSummary = sentenceCase(candidate.deliveryReason.summary, '');
     const availabilitySummary = candidate.online === true ? 'Online now.' : 'Currently offline.';
+    const roleSummary = candidate.worldRole ? `World role: ${candidate.worldRole}.` : null;
     const scoreSummary = candidate.score == null
       ? null
       : `Score ${candidate.score}${candidate.rank == null ? '' : `, rank ${candidate.rank}`}.`;
@@ -631,6 +638,7 @@ export function buildCandidateDeliverySummary(candidateFeed = {}, { worldDetail
       optionalFieldSummary.length > 0 ? `Optional context: ${optionalFieldSummary.join('; ')}.` : null,
       compatibilitySummary.length > 0 ? compatibilitySummary.join(' ') : null,
       deliveryReasonSummary || null,
+      roleSummary,
       availabilitySummary,
       scoreSummary,
     ].filter(Boolean).join(' ');
@@ -639,6 +647,7 @@ export function buildCandidateDeliverySummary(candidateFeed = {}, { worldDetail
       candidateId: candidate.candidateId,
       sourceMembershipId: candidate.sourceMembershipId,
       online: candidate.online === true,
+      worldRole: candidate.worldRole,
       agentCode: candidate.agentCode,
       requestChat: candidate.requestChat,
       displayName: name,