@xfxstudio/claworld 2026.7.2-testing.1 → 2026.7.8-testing.1

package/src/openclaw/plugin/register.js

@@ -25,10 +25,6 @@ import {
 } from '../runtime/working-memory.js';
 import { resolveOpenClawWorkspaceRoot } from '../runtime/workspace-resolver.js';
 import { setClaworldRuntime } from './runtime.js';
-import {
-  CHAT_REQUEST_APPROVAL_POLICY_MODES,
-  CHAT_REQUEST_APPROVAL_POLICY_ORIGIN_TYPES,
-} from '../../product-shell/contracts/chat-request-approval-policy.js';
 import { PUBLIC_TOOL_ACTION_CATALOG } from '../../product-shell/contracts/search-item.js';
 import {
   ACCOUNT_ACTIONS,
@@ -54,6 +50,8 @@ import {
   projectToolManageWorldActionResponse,
   requireManageWorldField,
   resolveToolContext,
+  resolveToolAgentId,
+  resolveToolDisplayName,
   stringParam,
   withToolErrorBoundary,
 } from './register-tooling.js';
@@ -236,13 +234,50 @@ function normalizeTerminalAccountAction(params = {}) {
     Object.prototype.hasOwnProperty.call(params, 'agentProfile')
     || Object.prototype.hasOwnProperty.call(params, 'profile')
   ) return 'update_agent_profile';
-  if (Object.prototype.hasOwnProperty.call(params, 'discoverable')) return 'set_discoverability';
-  if (Object.prototype.hasOwnProperty.call(params, 'contactable')) return 'set_contactability';
-  if (normalizeObject(params.chatRequestApprovalPolicy, null)) return 'set_chat_policy';
+  if (Object.prototype.hasOwnProperty.call(params, 'visibilityMode')) return 'set_visibility_mode';
+  if (Object.prototype.hasOwnProperty.call(params, 'contactPolicy')) return 'set_contact_policy';
+  if (Object.prototype.hasOwnProperty.call(params, 'chatRequestPolicy')) {
+    requireManageWorldField('chatRequestPolicy', 'chatRequestPolicy is not supported by claworld_manage_account; use contactPolicy');
+  }
   if (Object.prototype.hasOwnProperty.call(params, 'proactivitySettings')) return 'set_proactivity';
   return 'view_account';
 }
 
+function hasProvidedTerminalAccountPolicyField(params = {}, fieldId) {
+  if (!Object.prototype.hasOwnProperty.call(params, fieldId)) return false;
+  const value = params[fieldId];
+  if (value == null) return false;
+  if (typeof value === 'string') return normalizeText(value, null) != null;
+  return true;
+}
+
+function validateTerminalAccountPolicyPayload(action, params = {}) {
+  if (action === 'set_visibility_mode') {
+    if (!normalizeText(params.visibilityMode, null)) {
+      requireManageWorldField('visibilityMode', 'visibilityMode is required for action=set_visibility_mode');
+    }
+    if (hasProvidedTerminalAccountPolicyField(params, 'contactPolicy')) {
+      requireManageWorldField('contactPolicy', 'contactPolicy is not supported for action=set_visibility_mode');
+    }
+    if (hasProvidedTerminalAccountPolicyField(params, 'chatRequestPolicy')) {
+      requireManageWorldField('chatRequestPolicy', 'chatRequestPolicy is not supported by claworld_manage_account; use contactPolicy');
+    }
+    return;
+  }
+  if (action === 'set_contact_policy') {
+    if (!normalizeText(params.contactPolicy, null)) {
+      requireManageWorldField('contactPolicy', 'contactPolicy is required for action=set_contact_policy');
+    }
+    if (hasProvidedTerminalAccountPolicyField(params, 'visibilityMode')) {
+      requireManageWorldField('visibilityMode', 'visibilityMode is not supported for action=set_contact_policy');
+    }
+    if (hasProvidedTerminalAccountPolicyField(params, 'chatRequestPolicy')) {
+      requireManageWorldField('chatRequestPolicy', 'chatRequestPolicy is not supported by claworld_manage_account; use contactPolicy');
+    }
+    return;
+  }
+}
+
 function normalizeTerminalWorldAction(params = {}) {
   if (hasExplicitAction(params)) {
     const explicitAction = normalizeText(params.action, null);
@@ -470,12 +505,12 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
     {
       name: accountTool,
       label: 'Claworld Manage Account',
-      description: 'Terminal account surface for readiness, public identity, global profile, share-card generation, account-level chat policy, and email-based identity verification.',
+      description: 'Terminal account surface for readiness, public identity, global profile, share-card generation, visibility, inbound contact policy, and email-based identity verification.',
       metadata: buildToolMetadata({
         category: 'account',
         usageNotes: [
           'Use this human-facing account surface for identity verification, profile, policy, and subscription decisions.',
-          'Use action=view_account for readiness; update_display_name, update_agent_profile, or set_chat_policy for common account mutations.',
+          'Use action=view_account for readiness; update_display_name, update_agent_profile, or set_contact_policy for common account mutations.',
           'Use start_email_verification with email + optional displayName to start email-based identity verification, then complete_email_verification with email + code to finish.',
           'Use subscribe_person or unsubscribe_person when a search/profile result exposes a person subscription target.',
         ],
@@ -488,7 +523,7 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
           action: stringParam({
             description: 'Account action.',
             enumValues: TERMINAL_ACCOUNT_ACTIONS,
-            examples: ['view_account', 'start_email_verification', 'update_display_name', 'set_chat_policy'],
+            examples: ['view_account', 'start_email_verification', 'update_display_name', 'set_contact_policy'],
           }),
           displayName: stringParam({
             description: 'Public-facing display name for update_display_name or start_email_verification.',
@@ -507,11 +542,15 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
             description: 'Agent-facing profile/personality text for update_agent_profile.',
             examples: ['偏主动但会先确认边界，擅长总结和约局。'],
           }),
-          discoverable: booleanParam({ description: 'Whether this account can appear in global people search.' }),
-          contactable: booleanParam({ description: 'Whether this account can receive direct public-profile chat requests.' }),
-          chatRequestApprovalPolicy: objectParam({
-            description: 'Backend-managed inbound chat-request policy for this account.',
-            additionalProperties: true,
+          visibilityMode: stringParam({
+            description: 'Account visibility mode: public is searchable, unlisted is explicit-identity reachable, private is not publicly reachable.',
+            enumValues: ['public', 'unlisted', 'private'],
+            examples: ['public', 'unlisted', 'private'],
+          }),
+          contactPolicy: stringParam({
+            description: 'Inbound contact policy: open accepts eligible requests, approval_required keeps the request path open but requires review, closed blocks new inbound contact.',
+            enumValues: ['open', 'approval_required', 'closed'],
+            examples: ['open', 'approval_required', 'closed'],
           }),
           proactivitySettings: objectParam({
             description: 'Account-level proactive-management settings.',
@@ -554,6 +593,7 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
       }),
       async execute(toolCallId, params = {}) {
         const action = normalizeTerminalAccountAction(params);
+        validateTerminalAccountPolicyPayload(action, params);
         const subscriptionTargetId = normalizeText(params.targetAgentId, normalizeText(params.targetId, null));
         if (action === 'subscribe_person') {
           if (!subscriptionTargetId) requireManageWorldField('targetAgentId', 'targetAgentId is required for action=subscribe_person');
@@ -641,14 +681,20 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
           profile: params.profile,
           humanProfile: params.humanProfile,
           agentProfile: params.agentProfile,
-          discoverable: params.discoverable,
-          contactable: params.contactable,
-          chatRequestApprovalPolicy: params.chatRequestApprovalPolicy || null,
+          visibilityMode: params.visibilityMode,
+          contactPolicy: params.contactPolicy,
           proactivitySettings: params.proactivitySettings,
           generateShareCard,
           shareCardVariant: params.shareCardVariant ?? null,
           expiresInSeconds: params.expiresInSeconds ?? null,
         });
+        if (action === 'update_display_name') {
+          return buildToolResult(projectToolAccountMutationResponse({
+            action,
+            accountId: context.accountId,
+            identityPayload: payload,
+          }));
+        }
         return buildTerminalActionResult({ tool: accountTool, action, payload });
       },
     },
@@ -661,7 +707,7 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
         usageNotes: [
           'scope=worlds searches or browses visible worlds.',
           'scope=world_members searches members in an authorized world.',
-          'scope=people searches globally discoverable/contactable public identities.',
+          'scope=people searches globally public identities; unlisted people require explicit identity/profile lookup.',
           'scope=mixed combines world, optional world-member, and global people search results in one SearchItemEnvelope list.',
         ],
       }),
@@ -851,6 +897,7 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
         category: 'world_management',
         usageNotes: [
           'action=join_world joins a visible world with world-scoped profile text.',
+          'action=list_pending_invites lists pending world invitations received by the current account.',
           'action=create_world creates an owner-managed world.',
           'Owner governance and member self-service actions use terminal action names such as update_world, publish_broadcast, and update_world_profile.',
           'Subscription, activity, and member-list actions are backed by the product-shell terminal routes.',
@@ -970,6 +1017,18 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
           });
           return buildTerminalActionResult({ tool: manageWorldsTool, action, payload });
         }
+        if (action === 'list_pending_invites') {
+          const context = await resolveToolContext(api, plugin, params, {
+            requiredPublicIdentityCapability: 'list pending world invites',
+          });
+          const payload = await plugin.runtime.productShell.membership.listPendingInvites({
+            ...context,
+            status: params.status || 'pending',
+            includeDisabled: params.includeDisabled !== false,
+            limit: params.limit ?? null,
+          });
+          return buildTerminalActionResult({ tool: manageWorldsTool, action, payload });
+        }
         if (action === 'list_invites') {
           const worldId = normalizeText(params.worldId, null);
           if (!worldId) requireManageWorldField('worldId');
@@ -1200,43 +1259,6 @@ function buildRegisteredTools(api, plugin) {
     enumValues: ['en', 'zh'],
     examples: ['en', 'zh'],
   });
-  const chatRequestApprovalPolicyProperty = objectParam({
-    description: 'Backend-managed inbound chat-request policy for this account.',
-    required: ['mode'],
-    properties: {
-      mode: stringParam({
-        description: 'Policy mode controlling which new inbound chat requests auto-accept.',
-        enumValues: CHAT_REQUEST_APPROVAL_POLICY_MODES,
-        examples: ['open', 'manual_review'],
-      }),
-      blocks: objectParam({
-        description: 'Optional deny rules applied before the allow mode is evaluated.',
-        properties: {
-          originTypes: arrayParam({
-            description: 'Canonical request origin types that should always be rejected.',
-            items: stringParam({
-              enumValues: CHAT_REQUEST_APPROVAL_POLICY_ORIGIN_TYPES,
-            }),
-            examples: [['world_broadcast']],
-          }),
-          worldIds: arrayParam({
-            description: 'World ids that should always be rejected.',
-            items: stringParam({}),
-            examples: [['dating-demo-world']],
-          }),
-        },
-      }),
-    },
-    examples: [
-      {
-        mode: 'trusted_or_world',
-        blocks: {
-          originTypes: ['world_broadcast'],
-          worldIds: [],
-        },
-      },
-    ],
-  });
   const worldIdProperty = stringParam({
     description: 'Canonical world id returned by claworld_search(scope=worlds) or claworld_manage_worlds(action=get_world).',
     minLength: 1,
@@ -1925,20 +1947,6 @@ function buildRegisteredTools(api, plugin) {
             },
             outcome: 'Stores the current account profile text. Pass an empty string to clear it.',
           },
-          {
-            title: 'Update the inbound chat policy',
-            input: {
-              accountId: 'claworld',
-              action: 'update_chat_policy',
-              chatRequestApprovalPolicy: {
-                mode: 'trusted_or_world',
-                blocks: {
-                  originTypes: ['world_broadcast'],
-                },
-              },
-            },
-            outcome: 'Stores the account-level chat-request policy in the backend and returns the updated policy snapshot.',
-          },
         ],
       }),
       parameters: objectParam({
@@ -1947,9 +1955,9 @@ function buildRegisteredTools(api, plugin) {
         properties: {
           accountId: accountIdProperty,
           action: stringParam({
-            description: 'Account action. Defaults to view; inferred from displayName, profile, or chatRequestApprovalPolicy when omitted.',
+            description: 'Account action. Defaults to view; inferred from displayName or profile when omitted.',
             enumValues: ACCOUNT_ACTIONS,
-            examples: ['view', 'update_identity', 'update_profile', 'update_chat_policy'],
+            examples: ['view', 'update_identity', 'update_profile'],
           }),
           displayName: stringParam({
             description: 'Public-facing display name. Required for action=update_identity. # is reserved and must not appear here.',
@@ -1960,7 +1968,6 @@ function buildRegisteredTools(api, plugin) {
             description: 'Global plain-text profile for this account. Maximum 500 characters. Use an empty string to clear it. HTML is not supported.',
             examples: ['喜欢慢节奏介绍和小范围世界，也愿意先让 agent 帮我做初步认识。🙂'],
           }),
-          chatRequestApprovalPolicy: chatRequestApprovalPolicyProperty,
           generateShareCard: booleanParam({
             description: 'When true, return a temporary public identity card URL. Defaults to false for view and true for update_identity.',
           }),
@@ -1988,13 +1995,6 @@ function buildRegisteredTools(api, plugin) {
             action: 'update_profile',
             profile: '喜欢慢节奏介绍和小范围世界，也愿意先让 agent 帮我做初步认识。🙂',
           },
-          {
-            accountId: 'claworld',
-            action: 'update_chat_policy',
-            chatRequestApprovalPolicy: {
-              mode: 'manual_review',
-            },
-          },
         ],
       }),
       async execute(_toolCallId, params = {}) {
@@ -2040,26 +2040,6 @@ function buildRegisteredTools(api, plugin) {
           }));
         }
 
-        if (action === 'update_chat_policy') {
-          const context = await resolveToolContext(api, plugin, params);
-          const chatRequestApprovalPolicy = normalizeObject(params.chatRequestApprovalPolicy, null);
-          if (!chatRequestApprovalPolicy) {
-            requireManageWorldField(
-              'chatRequestApprovalPolicy',
-              'chatRequestApprovalPolicy is required for action=update_chat_policy',
-            );
-          }
-          const payload = await plugin.runtime.productShell.profile.updateChatRequestApprovalPolicy({
-            ...context,
-            chatRequestApprovalPolicy,
-          });
-          return buildToolResult(projectToolAccountMutationResponse({
-            action,
-            accountId: context.accountId,
-            identityPayload: payload,
-          }));
-        }
-
         const context = await resolveToolContext(api, plugin, params);
         const cfg = context.cfg || await loadCurrentConfig(api);
         const accountId = context.accountId;
@@ -2074,7 +2054,7 @@ function buildRegisteredTools(api, plugin) {
           shareCardVariant: params.shareCardVariant ?? null,
           expiresInSeconds: params.expiresInSeconds ?? null,
         });
-        const pairedAgentId = identityPayload?.agentId || runtimeConfig.relay?.agentId || null;
+        const pairedAgentId = resolveToolAgentId(identityPayload, runtimeConfig.relay?.agentId || null);
         const pairedRuntimeConfig = pairedAgentId
           ? {
             ...runtimeConfig,
@@ -2087,15 +2067,15 @@ function buildRegisteredTools(api, plugin) {
         const relayAgentFallback = pairedAgentId
           ? {
             agentId: pairedAgentId,
-            displayName: normalizeText(
-              identityPayload?.publicIdentity?.displayName,
+            displayName: resolveToolDisplayName(
+              identityPayload,
               normalizeText(
-                identityPayload?.recommendedDisplayName,
-                normalizeText(runtimeConfig?.name, normalizeText(runtimeConfig?.registration?.displayName, null)),
+                runtimeConfig?.name,
+                normalizeText(runtimeConfig?.registration?.displayName, null),
               ),
             ),
-            discoverable: null,
-            contactable: null,
+            visibilityMode: null,
+            contactPolicy: null,
             online: null,
             resolved: null,
           }
@@ -2113,7 +2093,13 @@ function buildRegisteredTools(api, plugin) {
             agentId: pairedAgentId,
           })
           : null;
-        const emailVerified = identityStatus?.emailVerified === true;
+        const accountPayload = normalizeObject(identityStatus?.accountView, null)
+          || (normalizeObject(identityStatus?.relay, null) ? identityStatus : null);
+        const accountViewAccount = normalizeObject(accountPayload?.account, null);
+        const accountViewDiagnostics = normalizeObject(accountPayload?.diagnostics, null);
+        const emailVerified = identityStatus?.emailVerified === true
+          || accountViewAccount?.emailVerified === true
+          || accountViewDiagnostics?.emailVerified === true;
         const bindingReady = hasConfiguredAppToken && Boolean(pairedAgentId);
         const bindingStatus = hasConfiguredAppToken
           ? (bindingReady ? 'bound' : 'identity_unresolved')
@@ -2140,8 +2126,8 @@ function buildRegisteredTools(api, plugin) {
           bindingReady,
           bindingStatus,
           emailVerified,
-          email: identityStatus?.email || null,
-          verifiedAt: identityStatus?.verifiedAt || null,
+          email: identityStatus?.email || accountViewAccount?.email || null,
+          verifiedAt: identityStatus?.verifiedAt || accountViewAccount?.verifiedAt || null,
           reason: hasConfiguredAppToken
             ? (pairedAgentId ? null : 'missing_agent_id')
             : 'missing_app_token',
@@ -2155,6 +2141,7 @@ function buildRegisteredTools(api, plugin) {
           accountId,
           pairingPayload,
           identityPayload,
+          accountPayload,
         }));
       },
     },

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

@@ -2,7 +2,10 @@ 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 {
+  CLAWORLD_OPENCLAW_PLUGIN_CLIENT,
+  CLAWORLD_PLUGIN_CURRENT_VERSION,
+} 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';
@@ -372,6 +375,7 @@ export class ClaworldRelayClient extends EventEmitter {
             type: 'auth',
             agentId,
             credential,
+            client: CLAWORLD_OPENCLAW_PLUGIN_CLIENT,
             clientVersion,
             bridgeProtocol: this.protocol.version,
           });
@@ -552,7 +556,7 @@ export class ClaworldRelayClient extends EventEmitter {
     config,
     agentId,
     credential = null,
-    clientVersion = buildClaworldRelayClientVersion(),
+    clientVersion = CLAWORLD_PLUGIN_CURRENT_VERSION,
     sessionTarget,
     fallbackTarget,
   } = {}) {

package/src/openclaw/plugin-version.js

@@ -1,7 +1,10 @@
 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';
+export const CLAWORLD_CLIENT_HEADER = 'x-claworld-client';
+export const CLAWORLD_CLIENT_VERSION_HEADER = 'x-claworld-client-version';
+export const CLAWORLD_CLIENT_CHANNEL_HEADER = 'x-claworld-client-channel';
+export const CLAWORLD_OPENCLAW_PLUGIN_CLIENT = 'openclaw-plugin';
 
 function normalizeText(value, fallback = null) {
   if (value == null) return fallback;
@@ -9,15 +12,6 @@ function normalizeText(value, fallback = null) {
   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;
@@ -39,16 +33,9 @@ function resolveCurrentPluginVersion() {
 
 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)}`;
+export function inferClaworldClientChannel(version = CLAWORLD_PLUGIN_CURRENT_VERSION, fallback = null) {
+  const normalized = normalizeClaworldPluginVersion(version, null);
+  if (!normalized) return fallback;
+  if (/-testing(?:\.|$)/.test(normalized)) return 'testing';
+  return 'stable';
 }

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

@@ -583,8 +583,8 @@ function projectToolAgentSummary(agent = {}) {
     displayName: normalizeText(agent.displayName, null),
     identity: normalizeText(agent.publicIdentity?.displayIdentity, null),
     online: agent.online === true,
-    discoverable: typeof agent.discoverable === 'boolean' ? agent.discoverable : null,
-    contactable: typeof agent.contactable === 'boolean' ? agent.contactable : null,
+    visibilityMode: normalizeText(agent.visibilityMode, null),
+    contactPolicy: normalizeText(agent.contactPolicy, null),
   };
 }
 

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

@@ -15,6 +15,23 @@ function normalizeOptionalBoolean(value, fallback = null) {
   return fallback;
 }
 
+function normalizeOptionalInteger(value, fallback = null) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.trunc(parsed);
+}
+
+function normalizePositiveInteger(value, fallback = null) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return Math.max(1, Math.trunc(parsed));
+}
+
+function normalizeStringList(values = []) {
+  if (!Array.isArray(values)) return [];
+  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;
@@ -38,6 +55,97 @@ function normalizeManagedWorldMembership(payload = {}) {
   };
 }
 
+function normalizePendingInviteAction(action = null) {
+  if (!action || typeof action !== 'object' || Array.isArray(action)) return null;
+  return {
+    action: normalizeText(action.action, null),
+    tool: normalizeText(action.tool, null),
+    worldId: normalizeText(action.worldId, null),
+    requiredFields: normalizeStringList(action.requiredFields),
+  };
+}
+
+function normalizeParticipantContextField(field = null) {
+  if (!field || typeof field !== 'object' || Array.isArray(field)) return null;
+  return {
+    fieldId: normalizeText(field.fieldId, null),
+    label: normalizeText(field.label, null),
+    description: normalizeText(field.description, null),
+  };
+}
+
+function normalizeJoinPlan(plan = null) {
+  if (!plan || typeof plan !== 'object' || Array.isArray(plan)) return null;
+  return {
+    worldId: normalizeText(plan.worldId, null),
+    participantContextField: normalizeParticipantContextField(plan.participantContextField),
+    nextAction: normalizeText(plan.nextAction, null),
+  };
+}
+
+function normalizeInviterProfile(inviter = null) {
+  if (!inviter || typeof inviter !== 'object' || Array.isArray(inviter)) return null;
+  return {
+    agentId: normalizeText(inviter.agentId, null),
+    displayName: normalizeText(inviter.displayName, null),
+    publicIdentity: normalizeText(inviter.publicIdentity, null),
+    profile: normalizeText(inviter.profile, null),
+  };
+}
+
+function normalizeInviteLifecycle(lifecycle = null) {
+  if (!lifecycle || typeof lifecycle !== 'object' || Array.isArray(lifecycle)) return null;
+  return {
+    status: normalizeText(lifecycle.status, null),
+    expiresAt: normalizeText(lifecycle.expiresAt, null),
+    expirationPolicy: normalizeText(lifecycle.expirationPolicy, null),
+    acceptedAt: normalizeText(lifecycle.acceptedAt, null),
+    inviteRevokedAt: normalizeText(lifecycle.inviteRevokedAt, null),
+  };
+}
+
+function normalizePendingWorldInvite(payload = {}) {
+  return {
+    invitationId: normalizeText(payload.invitationId, null),
+    membershipId: normalizeText(payload.membershipId, null),
+    agentId: normalizeText(payload.agentId, null),
+    worldId: normalizeText(payload.worldId, null),
+    displayName: normalizeText(payload.displayName, null),
+    worldContextText: normalizeText(payload.worldContextText, null),
+    participantContextField: normalizeParticipantContextField(payload.participantContextField),
+    joinPlan: normalizeJoinPlan(payload.joinPlan),
+    membershipStatus: normalizeText(payload.membershipStatus, null),
+    status: normalizeText(payload.status, null),
+    invitedByAgentId: normalizeText(payload.invitedByAgentId, null),
+    invitedByDisplayName: normalizeText(payload.invitedByDisplayName, null),
+    invitedByPublicIdentity: normalizeText(payload.invitedByPublicIdentity, null),
+    inviter: normalizeInviterProfile(payload.inviter),
+    invitedAt: normalizeText(payload.invitedAt, null),
+    inviteMessage: normalizeText(payload.inviteMessage, null),
+    expiresAt: normalizeText(payload.expiresAt, null),
+    expirationPolicy: normalizeText(payload.expirationPolicy, null),
+    lifecycle: normalizeInviteLifecycle(payload.lifecycle),
+    membershipUpdatedAt: normalizeText(payload.membershipUpdatedAt, null),
+    worldUpdatedAt: normalizeText(payload.worldUpdatedAt, null),
+    nextAction: normalizeText(payload.nextAction, null),
+    nextActions: Array.isArray(payload.nextActions)
+      ? payload.nextActions.map((action) => normalizePendingInviteAction(action)).filter(Boolean)
+      : [],
+  };
+}
+
+function normalizePendingWorldInviteList(payload = {}) {
+  return {
+    agentId: normalizeText(payload.agentId, null),
+    status: normalizeText(payload.status, null),
+    items: Array.isArray(payload.items)
+      ? payload.items.map((item) => normalizePendingWorldInvite(item))
+      : [],
+    totalItems: normalizeOptionalInteger(payload.totalItems, 0),
+    nextAction: normalizeText(payload.nextAction, null),
+  };
+}
+
 function normalizeMembershipList(payload = {}) {
   return {
     items: Array.isArray(payload.items)
@@ -116,6 +224,55 @@ export async function fetchWorldMemberships({
   return normalizeMembershipList(result.body);
 }
 
+export async function fetchPendingWorldInvites({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  agentId = null,
+  status = 'pending',
+  includeDisabled = true,
+  limit = 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 resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+  const requestUrl = new URL(`${baseUrl}/v1/world-invitations`);
+  requestUrl.searchParams.set('agentId', resolvedAgentId);
+  requestUrl.searchParams.set('status', normalizeText(status, 'pending'));
+  requestUrl.searchParams.set('includeDisabled', includeDisabled ? 'true' : 'false');
+  const normalizedLimit = normalizePositiveInteger(limit, null);
+  if (normalizedLimit) requestUrl.searchParams.set('limit', String(normalizedLimit));
+  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] pending world invites fetch failed', {
+      status: result.status,
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      body: result.body,
+    });
+    throw createWorldMembershipHttpError('list_pending_invites', result, {
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+    });
+  }
+
+  return normalizePendingWorldInviteList(result.body);
+}
+
 export async function fetchWorldMembership({
   cfg = {},
   accountId = null,

package/src/product-shell/contracts/chat-request-approval-policy.js

@@ -5,6 +5,7 @@ const SUPPORTED_MODES = Object.freeze([
   'trusted_only',
   'trusted_or_world',
   'open',
+  'reject_all',
 ]);
 const SUPPORTED_ORIGIN_TYPES = Object.freeze([
   'chat_request',
@@ -59,6 +60,11 @@ export function normalizeChatRequestApprovalMode(value, fallback = DEFAULT_MODE)
     case 'auto_accept':
     case 'all':
       return 'open';
+    case 'reject':
+    case 'reject_all':
+    case 'closed':
+    case 'do_not_disturb':
+      return 'reject_all';
     default:
       return SUPPORTED_MODES.includes(fallback) ? fallback : DEFAULT_MODE;
   }