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

package/openclaw.plugin.json

@@ -17,7 +17,7 @@
   },
   "name": "Claworld Persona Relay",
   "description": "Claworld relay world channel plugin for OpenClaw.",
-  "version": "2026.7.7-testing.1",
+  "version": "2026.7.8-testing.1",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfxstudio/claworld",
-  "version": "2026.7.7-testing.1",
+  "version": "2026.7.8-testing.1",
   "description": "Claworld channel plugin for OpenClaw",
   "type": "module",
   "main": "index.js",

package/skills/claworld-manage-worlds/SKILL.md

@@ -31,6 +31,7 @@ All world management goes through `claworld_manage_worlds`:
 - `list_world_activity`
 - `list_broadcast_history`
 - `manage_members`
+- `list_pending_invites`
 - `list_invites`
 - `invite_member`
 - `revoke_invite`
@@ -95,12 +96,20 @@ When the human needs to create or update a world and `worldContextText` is empty
 2. `update_world_profile` or `leave_world`
 3. `subscribe_world` / `unsubscribe_world` when ongoing attention is desired
 
+### Reviewing Received Invites
+
+1. `list_pending_invites`
+2. Treat the returned item as the pre-join private-world invitation preview.
+3. Explain the inviter, inviter profile, world purpose, world fit, invitation note, lifecycle state, and available next actions in natural language.
+4. Join with `join_world` only after the human confirms the world-scoped `participantContextText`.
+
 ## Quick Reference
 
 - Create world: `claworld_manage_worlds(action=create_world, displayName, worldContextText, participantContextText)`
 - Get world: `claworld_manage_worlds(action=get_world, worldId)`
 - List owned: `claworld_manage_worlds(action=list_owned_worlds)`
 - List joined: `claworld_manage_worlds(action=list_joined_worlds)`
+- Pending invites received by this account: `claworld_manage_worlds(action=list_pending_invites)`
 - Join world: `claworld_manage_worlds(action=join_world, worldId, participantContextText)`
 - Update participant profile: `claworld_manage_worlds(action=update_world_profile, worldId, profileContextText)`
 - Leave world: `claworld_manage_worlds(action=leave_world, worldId)`

package/skills/claworld-management-session/SKILL.md

@@ -91,6 +91,7 @@ Before starting or judging a conversation, usually check the relevant pieces:
 - the owner's current goals and memory in `.claworld/`
 - the person's public profile
 - the world, membership, and join context
+- pending world invitations received by this account
 - existing active, opening, pending, silent, or ended conversations with the same person
 
 Prefer the normal Claworld tools for product work:

package/src/openclaw/index.js

@@ -63,6 +63,7 @@ export {
   manageModeratedWorld,
 } from './runtime/world-moderation-helper.js';
 export {
+  fetchPendingWorldInvites,
   fetchWorldMemberships,
   fetchWorldMembership,
   updateWorldMembershipProfile,

package/src/openclaw/plugin/claworld-channel-plugin.js

@@ -53,6 +53,7 @@ import {
   revokeModeratedWorldInvite,
 } from '../runtime/world-moderation-helper.js';
 import {
+  fetchPendingWorldInvites,
   fetchWorldMembership,
   fetchWorldMemberships,
   leaveWorldMembership,
@@ -271,6 +272,18 @@ function isClaworldPlainObject(value) {
   return value && typeof value === 'object' && !Array.isArray(value);
 }
 
+function resolveAccountProfileEnvelope(payload = null) {
+  return isClaworldPlainObject(payload?.profile) ? payload.profile : null;
+}
+
+function resolveAccountAgentId(payload = null, fallback = null) {
+  const profile = resolveAccountProfileEnvelope(payload);
+  return normalizeClaworldText(
+    payload?.agentId,
+    normalizeClaworldText(profile?.agentId, fallback),
+  );
+}
+
 function resolveClaworldOpeningMessage({
   openingMessage = null,
   message = null,
@@ -2070,7 +2083,7 @@ async function ensureRelayBinding({ runtimeConfig, fetchImpl, logger }) {
       expiresInSeconds: null,
       fetchImpl,
     });
-    const resolvedAgentId = normalizeClaworldText(identityPayload?.agentId, null);
+    const resolvedAgentId = resolveAccountAgentId(identityPayload, null);
     if (resolvedAgentId) {
       return {
         runtimeConfig: applyRuntimeIdentity(normalizedRuntimeConfig, { agentId: resolvedAgentId }),
@@ -4350,7 +4363,10 @@ async function generateRuntimeProfileCard(context = {}) {
     shareCardVariant: context.shareCardVariant ?? null,
     fetchImpl,
   });
-  return result?.shareCard || {};
+  const profileEnvelope = result?.profile && typeof result.profile === 'object' && !Array.isArray(result.profile)
+    ? result.profile
+    : null;
+  return profileEnvelope?.shareCard || {};
 }
 
   return {
@@ -4946,6 +4962,20 @@ async function generateRuntimeProfileCard(context = {}) {
             logger,
           });
         },
+        listPendingInvites: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return fetchPendingWorldInvites({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            agentId: resolvedContext.agentId || null,
+            status: context.status || 'pending',
+            includeDisabled: context.includeDisabled !== false,
+            limit: context.limit ?? null,
+            fetchImpl,
+            logger,
+          });
+        },
         getWorldMembership: async (context = {}) => {
           const resolvedContext = await resolveBoundRuntimeContext(context);
           return fetchWorldMembership({
@@ -5372,6 +5402,20 @@ async function generateRuntimeProfileCard(context = {}) {
               logger,
             });
           },
+          listPendingInvites: async (context = {}) => {
+            const resolvedContext = await resolveBoundRuntimeContext(context);
+            return fetchPendingWorldInvites({
+              cfg: resolvedContext.cfg || {},
+              accountId: resolvedContext.accountId || null,
+              runtimeConfig: resolvedContext.runtimeConfig || null,
+              agentId: resolvedContext.agentId || null,
+              status: context.status || 'pending',
+              includeDisabled: context.includeDisabled !== false,
+              limit: context.limit ?? null,
+              fetchImpl,
+              logger,
+            });
+          },
           getWorldMembership: async (context = {}) => {
             const resolvedContext = await resolveBoundRuntimeContext(context);
             return fetchWorldMembership({

package/src/openclaw/plugin/register-tooling.js

@@ -32,6 +32,56 @@ export function normalizeObject(value, fallback = null) {
   return value;
 }
 
+function normalizePlainText(value, fallback = null) {
+  if (value == null || typeof value === 'object' || typeof value === 'function') return fallback;
+  return normalizeText(value, fallback);
+}
+
+function resolveAccountManagementProfilePayload(payload = null) {
+  return normalizeObject(payload?.profile, null);
+}
+
+function resolveToolIdentityPayload(payload = null) {
+  return resolveAccountManagementProfilePayload(payload) || normalizeObject(payload, null);
+}
+
+function resolveToolPublicIdentityPayload(payload = null) {
+  const identityPayload = resolveToolIdentityPayload(payload);
+  return normalizeObject(identityPayload?.publicIdentity, null);
+}
+
+function resolveToolAccountProfilePayload(payload = null) {
+  const identityPayload = resolveToolIdentityPayload(payload);
+  return normalizeObject(identityPayload?.accountProfile, null);
+}
+
+function resolveToolShareCardPayload(payload = null) {
+  const identityPayload = resolveToolIdentityPayload(payload);
+  if (identityPayload && Object.prototype.hasOwnProperty.call(identityPayload, 'shareCard')) {
+    return identityPayload.shareCard;
+  }
+  return undefined;
+}
+
+function resolveToolPluginVersionPayload(payload = null) {
+  const identityPayload = resolveToolIdentityPayload(payload);
+  return identityPayload?.clientVersionStatus || null;
+}
+
+export function resolveToolAgentId(payload = null, fallback = null) {
+  const identityPayload = resolveToolIdentityPayload(payload);
+  return normalizePlainText(identityPayload?.agentId, fallback);
+}
+
+export function resolveToolDisplayName(payload = null, fallback = null) {
+  const identityPayload = resolveToolIdentityPayload(payload);
+  const publicIdentity = resolveToolPublicIdentityPayload(payload);
+  return normalizePlainText(
+    publicIdentity?.displayName,
+    normalizePlainText(identityPayload?.recommendedDisplayName, fallback),
+  );
+}
+
 function resolveRuntimeAppToken(runtimeConfig = {}) {
   return normalizeText(
     runtimeConfig?.appToken,
@@ -94,7 +144,7 @@ async function buildPendingPublicIdentityError({
       accountId: normalizeText(accountId, null),
       agentId: normalizeText(
         agentId,
-        normalizeText(identityPayload?.agentId, null),
+        resolveToolAgentId(identityPayload, null),
       ),
       httpStatus: 409,
       backendCode: 'public_identity_incomplete',
@@ -512,31 +562,36 @@ export function inferAccountAction(params = {}) {
 }
 
 function projectToolPublicIdentity(payload = null) {
-  if (!payload || typeof payload !== 'object') return null;
+  const identityPayload = resolveToolIdentityPayload(payload);
+  if (!identityPayload) return null;
+  const publicIdentity = resolveToolPublicIdentityPayload(payload);
   return {
-    status: payload.status || null,
-    ready: payload.ready ?? null,
-    publicIdentity: payload.publicIdentity && typeof payload.publicIdentity === 'object'
+    status: normalizePlainText(identityPayload.status, null),
+    ready: identityPayload.ready ?? null,
+    publicIdentity: publicIdentity
       ? {
-          status: payload.publicIdentity.status || null,
-          displayIdentity: payload.publicIdentity.displayIdentity || null,
-          displayName: payload.publicIdentity.displayName || null,
-          code: payload.publicIdentity.code || null,
-          confirmedAt: payload.publicIdentity.confirmedAt || null,
-          updatedAt: payload.publicIdentity.updatedAt || null,
+          status: normalizePlainText(publicIdentity.status, null),
+          displayIdentity: normalizePlainText(publicIdentity.displayIdentity, null),
+          displayName: normalizePlainText(publicIdentity.displayName, null),
+          code: normalizePlainText(publicIdentity.code, null),
+          confirmedAt: normalizePlainText(publicIdentity.confirmedAt, null),
+          updatedAt: normalizePlainText(publicIdentity.updatedAt, null),
         }
       : null,
-    recommendedDisplayName: payload.recommendedDisplayName || null,
-    requiredAction: payload.requiredAction || null,
-    nextAction: payload.nextAction || null,
-    nextTool: payload.nextTool || null,
-    missingFields: Array.isArray(payload.missingFields) ? payload.missingFields : [],
-    feedbackSummary: payload.feedbackSummary && typeof payload.feedbackSummary === 'object'
+    recommendedDisplayName: normalizePlainText(
+      identityPayload.recommendedDisplayName,
+      null,
+    ),
+    requiredAction: normalizePlainText(identityPayload.requiredAction, null),
+    nextAction: normalizePlainText(identityPayload.nextAction, null),
+    nextTool: normalizePlainText(identityPayload.nextTool, null),
+    missingFields: Array.isArray(identityPayload.missingFields) ? identityPayload.missingFields : [],
+    feedbackSummary: identityPayload.feedbackSummary && typeof identityPayload.feedbackSummary === 'object'
       ? {
-          totalLikesReceived: Number(payload.feedbackSummary.totalLikesReceived || 0),
-          totalDislikesReceived: Number(payload.feedbackSummary.totalDislikesReceived || 0),
-          totalLikesGiven: Number(payload.feedbackSummary.totalLikesGiven || 0),
-          totalDislikesGiven: Number(payload.feedbackSummary.totalDislikesGiven || 0),
+          totalLikesReceived: Number(identityPayload.feedbackSummary.totalLikesReceived || 0),
+          totalDislikesReceived: Number(identityPayload.feedbackSummary.totalDislikesReceived || 0),
+          totalLikesGiven: Number(identityPayload.feedbackSummary.totalLikesGiven || 0),
+          totalDislikesGiven: Number(identityPayload.feedbackSummary.totalDislikesGiven || 0),
         }
       : null,
   };
@@ -596,23 +651,28 @@ function projectToolAccountIdentityFields(identityPayload = null) {
 }
 
 function projectToolAccountProfile(identityPayload = null) {
-  return normalizeText(identityPayload?.profile, null);
+  const identityPayloadSource = resolveToolIdentityPayload(identityPayload);
+  const profilePayload = resolveToolAccountProfilePayload(identityPayload);
+  return normalizePlainText(
+    profilePayload?.profile,
+    normalizePlainText(identityPayloadSource?.profile, null),
+  );
 }
 
 function projectToolAccountProfileState(identityPayload = null) {
-  const profilePayload = normalizeObject(identityPayload?.accountProfile, null);
-  const profile = normalizeText(profilePayload?.profile, projectToolAccountProfile(identityPayload));
+  const profilePayload = resolveToolAccountProfilePayload(identityPayload);
+  const profile = normalizePlainText(profilePayload?.profile, projectToolAccountProfile(identityPayload));
   const ready = profilePayload
     ? profilePayload.ready === true
     : Boolean(profile);
   return {
-    status: normalizeText(profilePayload?.status, ready ? 'ready' : 'pending'),
+    status: normalizePlainText(profilePayload?.status, ready ? 'ready' : 'pending'),
     ready,
     profile,
-    reason: normalizeText(profilePayload?.reason, ready ? null : 'account_profile_missing'),
-    requiredAction: normalizeText(profilePayload?.requiredAction, ready ? null : 'update_agent_profile'),
-    nextAction: normalizeText(profilePayload?.nextAction, ready ? null : 'update_agent_profile'),
-    nextTool: normalizeText(profilePayload?.nextTool, ready ? null : 'claworld_manage_account'),
+    reason: normalizePlainText(profilePayload?.reason, ready ? null : 'account_profile_missing'),
+    requiredAction: normalizePlainText(profilePayload?.requiredAction, ready ? null : 'update_agent_profile'),
+    nextAction: normalizePlainText(profilePayload?.nextAction, ready ? null : 'update_agent_profile'),
+    nextTool: normalizePlainText(profilePayload?.nextTool, ready ? null : 'claworld_manage_account'),
     missingFields: Array.isArray(profilePayload?.missingFields)
       ? profilePayload.missingFields
       : (ready
@@ -630,9 +690,9 @@ function projectToolAccountProfileState(identityPayload = null) {
 function resolveToolPublicIdentityReady(identityPayload = null, publicIdentityState = {}) {
   const diagnostics = normalizeObject(identityPayload?.diagnostics, null);
   if (typeof diagnostics?.publicIdentityReady === 'boolean') return diagnostics.publicIdentityReady;
-  const identityStatus = normalizeText(publicIdentityState?.publicIdentity?.status, null);
+  const identityStatus = normalizePlainText(publicIdentityState?.publicIdentity?.status, null);
   if (identityStatus) return identityStatus === 'ready';
-  return identityPayload?.ready === true;
+  return resolveToolIdentityPayload(identityPayload)?.ready === true || identityPayload?.ready === true;
 }
 
 function projectToolPluginVersionStatus(payload = null) {
@@ -746,8 +806,9 @@ export function projectToolAccountViewResponse({
   const relayResolved = typeof accountRelay?.resolved === 'boolean'
     ? accountRelay.resolved
     : (typeof relayOnline === 'boolean');
-  const resolvedShareCard = identityPayload && Object.prototype.hasOwnProperty.call(identityPayload, 'shareCard')
-    ? projectToolShareCard(identityPayload.shareCard)
+  const shareCardPayload = resolveToolShareCardPayload(identityPayload);
+  const resolvedShareCard = shareCardPayload !== undefined
+    ? projectToolShareCard(shareCardPayload)
     : undefined;
   return {
     action: 'view',
@@ -799,7 +860,7 @@ export function projectToolAccountViewResponse({
     nextAction: blockedAction.nextAction,
     nextTool: blockedAction.nextTool,
     missingFields: blockedAction.missingFields,
-    pluginVersionStatus: projectToolPluginVersionStatus(identityPayload?.pluginVersionStatus),
+    pluginVersionStatus: projectToolPluginVersionStatus(resolveToolPluginVersionPayload(identityPayload)),
     ...(resolvedShareCard !== undefined ? { shareCard: resolvedShareCard } : {}),
   };
 }
@@ -813,10 +874,11 @@ export function projectToolAccountMutationResponse({
 } = {}) {
   const publicIdentityState = projectToolAccountIdentityFields(identityPayload);
   const accountProfile = projectToolAccountProfileState(identityPayload);
+  const identityShareCardPayload = resolveToolShareCardPayload(identityPayload);
   const resolvedShareCard = shareCard !== undefined
     ? shareCard
-    : (identityPayload && Object.prototype.hasOwnProperty.call(identityPayload, 'shareCard')
-        ? projectToolShareCard(identityPayload.shareCard)
+    : (identityShareCardPayload !== undefined
+        ? projectToolShareCard(identityShareCardPayload)
         : undefined);
   const publicIdentityReady = resolveToolPublicIdentityReady(identityPayload, publicIdentityState);
   const accountProfileReady = accountProfile.ready === true;
@@ -885,7 +947,7 @@ export function projectToolAccountMutationResponse({
     nextTool: blockedAction.nextTool,
     missingFields: blockedAction.missingFields,
     reason: blockedAction.reason,
-    pluginVersionStatus: projectToolPluginVersionStatus(identityPayload?.pluginVersionStatus),
+    pluginVersionStatus: projectToolPluginVersionStatus(resolveToolPluginVersionPayload(identityPayload)),
     ...(resolvedShareCard !== undefined ? { shareCard: resolvedShareCard } : {}),
     ...(runtimeIdentity ? { runtimeIdentity } : {}),
     ...(action === 'update_identity'

package/src/openclaw/plugin/register.js

@@ -50,6 +50,8 @@ import {
   projectToolManageWorldActionResponse,
   requireManageWorldField,
   resolveToolContext,
+  resolveToolAgentId,
+  resolveToolDisplayName,
   stringParam,
   withToolErrorBoundary,
 } from './register-tooling.js';
@@ -686,6 +688,13 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
           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 });
       },
     },
@@ -888,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.',
@@ -1007,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');
@@ -2032,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,
@@ -2045,11 +2067,11 @@ 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),
               ),
             ),
             visibilityMode: 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/search-item.js

@@ -59,6 +59,7 @@ export const PUBLIC_TOOL_ACTION_CATALOG = Object.freeze({
     'list_world_activity',
     'list_broadcast_history',
     'manage_members',
+    'list_pending_invites',
     'list_invites',
     'invite_member',
     'revoke_invite',