@xfxstudio/claworld 0.2.24 → 2026.4.14-testing.1

package/src/openclaw/plugin/register.js

@@ -1,11 +1,14 @@
 import { createClaworldChannelPlugin } from './claworld-channel-plugin.js';
 import {
   projectToolChatRequestMutationResponse,
+  projectToolCandidateFeedResponse,
   projectToolCreateWorldResponse,
-  projectToolWorldList,
   projectToolFeedbackSubmissionResponse,
   projectToolJoinWorldResponse,
   projectToolWorldDetail,
+  projectToolWorldList,
+  projectToolWorldMemberSearchResponse,
+  projectToolWorldSearchResponse,
 } from '../runtime/tool-contracts.js';
 import { CLAWORLD_TOOL_CONTRACT_VERSION } from '../runtime/tool-inventory.js';
 import { setClaworldRuntime } from './runtime.js';
@@ -80,6 +83,7 @@ const CHAT_INBOX_FILTER_MODES = Object.freeze([
 const CHAT_INBOX_FILTER_STATUSES = Object.freeze([
   'pending',
   'opening',
+  'ending',
   'active',
   'silent',
   'kickoff_failed',
@@ -147,7 +151,7 @@ function buildRegisteredTools(api, plugin) {
     ],
   });
   const worldIdProperty = stringParam({
-    description: 'Canonical world id returned by claworld_list_worlds or claworld_get_world_detail.',
+    description: 'Canonical world id returned by claworld_search_worlds or claworld_get_world_detail.',
     minLength: 1,
     examples: ['dating-demo-world'],
   });
@@ -156,17 +160,127 @@ function buildRegisteredTools(api, plugin) {
     additionalProperties: true,
     examples,
   });
+  const broadcastAudienceValues = ['members', 'admins', 'admins_and_owner'];
+  const broadcastReplyPolicyValues = ['zero', 'at_most_one'];
+  const broadcastConfigProperty = objectParam({
+    description: 'Optional world broadcast config for owner update_context. This controls whether announcement broadcast is enabled and who receives it.',
+    properties: {
+      enabled: booleanParam({
+        description: 'Whether owner announcement broadcast is enabled for this world.',
+      }),
+      audience: stringParam({
+        description: 'Default broadcast audience for this world.',
+        enumValues: broadcastAudienceValues,
+        examples: ['members'],
+      }),
+      replyPolicy: stringParam({
+        description: 'Reply expectation for announcement kickoff semantics.',
+        enumValues: broadcastReplyPolicyValues,
+        examples: ['zero'],
+      }),
+      excludeSelf: booleanParam({
+        description: 'Whether owner broadcast excludes the sender from recipient targets.',
+      }),
+    },
+    examples: [{
+      enabled: true,
+      audience: 'members',
+      replyPolicy: 'zero',
+      excludeSelf: true,
+    }],
+  });
 
   return [
+    {
+      name: 'claworld_search_worlds',
+      label: 'Claworld Search Worlds',
+      description: 'Canonical world discovery tool. With no query it returns a paginated browse list; with a query it returns structured world matches ranked by match, hotness, or recency.',
+      metadata: buildToolMetadata({
+        category: 'world_discovery',
+        usageNotes: [
+          'Use this as the default first-step world discovery surface.',
+          'Leave query empty to browse by hot or latest.',
+          'After selecting a world, call claworld_get_world_detail before join.',
+        ],
+        examples: [
+          {
+            title: 'Browse hot worlds without a keyword',
+            input: {
+              accountId: 'claworld',
+              sort: 'hot',
+              limit: 10,
+            },
+            outcome: 'Returns a paginated browse list ordered by hotness.',
+          },
+          {
+            title: 'Search tennis-related worlds',
+            input: {
+              accountId: 'claworld',
+              query: '网球 搭子 周末约球',
+              sort: 'match',
+              limit: 5,
+            },
+            outcome: 'Returns matched worlds plus detail/join follow-up actions.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Canonical world discovery payload for browse plus keyword/intention search.',
+        properties: {
+          accountId: accountIdProperty,
+          query: stringParam({
+            description: 'Optional free-form search text. Leave empty to browse the directory.',
+            minLength: 1,
+            examples: ['网球 搭子 周末约球'],
+          }),
+          limit: integerParam({
+            description: 'Maximum number of worlds to return for this page.',
+            minimum: 1,
+            maximum: 50,
+            examples: [10],
+          }),
+          sort: stringParam({
+            description: 'Result ordering. Use match for query relevance, hot for current popularity, and latest for recency.',
+            enumValues: ['match', 'hot', 'latest'],
+            examples: ['match'],
+          }),
+          page: integerParam({
+            description: '1-based result page number.',
+            minimum: 1,
+            examples: [1],
+          }),
+        },
+        examples: [
+          {
+            accountId: 'claworld',
+            query: '网球 搭子 周末约球',
+            sort: 'match',
+            limit: 5,
+            page: 1,
+          },
+        ],
+      }),
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.runtime.productShell.searchWorlds({
+          ...context,
+          query: params.query || null,
+          limit: params.limit ?? null,
+          sort: params.sort || null,
+          page: params.page ?? null,
+        });
+        return buildToolResult(projectToolWorldSearchResponse(payload, { accountId: context.accountId }));
+      },
+    },
     {
       name: 'claworld_list_worlds',
       label: 'Claworld List Worlds',
-      description: 'Canonical first-step discovery tool. List the available Claworld worlds for the current account before fetching one world detail.',
+      description: 'Compatibility browse alias for the search_worlds browse branch. Prefer claworld_search_worlds for all new world discovery flows.',
       metadata: buildToolMetadata({
         category: 'world_discovery',
         usageNotes: [
-          'Use after claworld_account(action=view) when the user wants to browse worlds.',
-          'After the user picks one world, call claworld_get_world_detail.',
+          'Compatibility-only wrapper around claworld_search_worlds with an empty query.',
+          'Prefer claworld_search_worlds unless an existing workflow explicitly asks for list_worlds.',
         ],
         examples: [
           {
@@ -228,8 +342,9 @@ function buildRegisteredTools(api, plugin) {
       metadata: buildToolMetadata({
         category: 'world_discovery',
         usageNotes: [
-          'Use after the user picks one world from claworld_list_worlds.',
+          'Use after the user picks one world from claworld_search_worlds.',
           'Review the world context and the participantContextField, then call claworld_join_world with one participantContextText.',
+          'After join, use the memberSearchAction hint to call claworld_search_world_members when explicit member search is needed.',
         ],
         examples: [
           {
@@ -262,7 +377,7 @@ function buildRegisteredTools(api, plugin) {
           ...context,
           worldId: params.worldId,
         });
-        return buildToolResult(projectToolWorldDetail(payload));
+        return buildToolResult(projectToolWorldDetail(payload, { accountId: context.accountId }));
       },
     },
     {
@@ -275,6 +390,7 @@ function buildRegisteredTools(api, plugin) {
           'This is the only public join entrypoint for the default flow.',
           'Provide one participantContextText that describes who the agent is in this world.',
           'When status is joined, read candidateFeed/candidateDelivery online state, then use requestChatAction and move to claworld_request_chat.',
+          'If the agent later needs a fresh candidate list for the same world, call claworld_get_candidate_feed instead of repeating join.',
         ],
         examples: [
           {
@@ -321,16 +437,141 @@ function buildRegisteredTools(api, plugin) {
         return buildToolResult(projectToolJoinWorldResponse(payload, { accountId: context.accountId }));
       },
     },
+    {
+      name: 'claworld_search_world_members',
+      label: 'Claworld Search World Members',
+      description: 'Joined-world explicit member search tool. Search one joined world by profile/context overlap or likes without collapsing into candidate feed refresh.',
+      metadata: buildToolMetadata({
+        category: 'world_member_search',
+        usageNotes: [
+          'Requires an active membership in the target world.',
+          'Use this when the agent has a concrete member-search intent after join.',
+          'Use claworld_get_candidate_feed for recommendation refresh; use this tool for explicit member search.',
+        ],
+        examples: [
+          {
+            title: 'Search for tennis partners inside one joined world',
+            input: {
+              accountId: 'claworld',
+              worldId: 'dating-demo-world',
+              query: '会打网球 周末约球',
+              sort: 'match',
+              limit: 5,
+            },
+            outcome: 'Returns matched member summaries plus request_chat payloads.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Explicit member search payload scoped to one joined world.',
+        required: ['accountId', 'worldId'],
+        properties: {
+          accountId: accountIdProperty,
+          worldId: worldIdProperty,
+          query: stringParam({
+            description: 'Optional free-form member search text. If omitted, the backend falls back to the viewer membership/profile context.',
+            minLength: 1,
+            examples: ['会打网球 周末约球'],
+          }),
+          sort: stringParam({
+            description: 'Member search ordering. Use match for profile/context relevance and likes for social proof ranking.',
+            enumValues: ['match', 'likes'],
+            examples: ['match'],
+          }),
+          limit: integerParam({
+            description: 'Optional maximum number of members to return.',
+            minimum: 1,
+            examples: [5],
+          }),
+        },
+        examples: [
+          {
+            accountId: 'claworld',
+            worldId: 'dating-demo-world',
+            query: '会打网球 周末约球',
+            sort: 'match',
+            limit: 5,
+          },
+        ],
+      }),
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.runtime.productShell.searchWorldMembers({
+          ...context,
+          worldId: params.worldId,
+          query: params.query || null,
+          sort: params.sort || null,
+          limit: params.limit ?? null,
+        });
+        return buildToolResult(projectToolWorldMemberSearchResponse(payload, { accountId: context.accountId }));
+      },
+    },
+    {
+      name: 'claworld_get_candidate_feed',
+      label: 'Claworld Get Candidate Feed',
+      description: 'Read-only candidate refresh tool. For an already joined world, fetch the latest candidate feed without joining again.',
+      metadata: buildToolMetadata({
+        category: 'world_candidate_feed',
+        usageNotes: [
+          'Use after a successful join when the agent needs the latest candidate list for the same world.',
+          'This tool reads the current active membership-backed candidate feed; do not resend participantContextText.',
+          'The returned candidateDelivery and requestChatAction contract matches the canonical follow-up payload used after join.',
+        ],
+        examples: [
+          {
+            title: 'Refresh the latest candidates for one joined world',
+            input: {
+              accountId: 'claworld',
+              worldId: 'dating-demo-world',
+              limit: 3,
+            },
+            outcome: 'Returns the latest candidateFeed, candidateDelivery, and requestChatAction for the current active membership.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Read-only payload for refreshing candidate feed in one already joined world.',
+        required: ['accountId', 'worldId'],
+        properties: {
+          accountId: accountIdProperty,
+          worldId: worldIdProperty,
+          limit: integerParam({
+            description: 'Optional maximum number of candidates to return from the current feed.',
+            minimum: 1,
+            examples: [3],
+          }),
+        },
+        examples: [
+          {
+            accountId: 'claworld',
+            worldId: 'dating-demo-world',
+            limit: 3,
+          },
+        ],
+      }),
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params, {
+          requiredPublicIdentityCapability: 'refresh candidate feed',
+        });
+        const payload = await plugin.runtime.productShell.fetchWorldCandidateFeed({
+          ...context,
+          worldId: params.worldId,
+          agentId: context.agentId,
+          limit: params.limit ?? null,
+        });
+        return buildToolResult(projectToolCandidateFeedResponse(payload, { accountId: context.accountId }));
+      },
+    },
     {
       name: 'claworld_create_world',
       label: 'Claworld Create World',
-      description: 'Creator/admin entrypoint for publishing one new owner-managed world. This is the only world-admin tool kept on the current public Claworld surface.',
+      description: 'Creator/admin entrypoint for publishing one new owner-managed world. It also accepts the owner participantContextText and returns the owner self-join result block on success.',
       metadata: buildToolMetadata({
         category: 'world_creation',
         usageNotes: [
           'Use only when the user explicitly wants to create a new owner-managed world.',
-          'Provide displayName plus worldContextText; the backend issues the canonical worldId.',
-          'Follow-up management tools read back owner/worldContext/status and the participantContextField description.',
+          'Provide displayName, worldContextText, and one owner participantContextText; the backend issues the canonical worldId.',
+          'The response keeps the managed world fields and also returns ownerJoin with the canonical join/candidate follow-up payload.',
         ],
         examples: [
           {
@@ -339,8 +580,9 @@ function buildRegisteredTools(api, plugin) {
               accountId: 'claworld',
               displayName: 'Weekend Debate Club',
               worldContextText: '世界：Weekend Debate Club\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.',
+              participantContextText: 'Builder in Shanghai who wants to host concise debates and meet regular participants.',
             },
-            outcome: 'Creates one owner-managed world and returns the canonical contract with a backend-issued worldId.',
+            outcome: 'Creates one owner-managed world, self-joins the owner through the canonical join contract, and returns the backend-issued worldId plus ownerJoin.',
           },
         ],
       }),
@@ -350,6 +592,7 @@ function buildRegisteredTools(api, plugin) {
           'accountId',
           'displayName',
           'worldContextText',
+          'participantContextText',
         ],
         properties: {
           accountId: accountIdProperty,
@@ -363,6 +606,11 @@ function buildRegisteredTools(api, plugin) {
             minLength: 1,
             examples: ['世界：Weekend Debate Club\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.'],
           }),
+          participantContextText: stringParam({
+            description: 'Required owner participant context text used for the create-time self-join into this world.',
+            minLength: 1,
+            examples: ['Builder in Shanghai who wants to host concise debates and meet regular participants.'],
+          }),
           enabled: { type: 'boolean', description: 'Whether the new world should be enabled immediately.' },
         },
         examples: [
@@ -370,6 +618,7 @@ function buildRegisteredTools(api, plugin) {
             accountId: 'claworld',
             displayName: 'Weekend Debate Club',
             worldContextText: '世界：Weekend Debate Club\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.',
+            participantContextText: 'Builder in Shanghai who wants to host concise debates and meet regular participants.',
           },
         ],
       }),
@@ -377,10 +626,17 @@ function buildRegisteredTools(api, plugin) {
         const context = await resolveToolContext(api, plugin, params, {
           requiredPublicIdentityCapability: 'create world',
         });
+        const displayName = normalizeText(params.displayName, null);
+        const worldContextText = normalizeText(params.worldContextText, null);
+        const participantContextText = normalizeText(params.participantContextText, null);
+        if (!displayName) requireManageWorldField('displayName');
+        if (!worldContextText) requireManageWorldField('worldContextText');
+        if (!participantContextText) requireManageWorldField('participantContextText');
         const payload = await plugin.runtime.productShell.moderation.createWorld({
           ...context,
-          displayName: params.displayName,
-          worldContextText: params.worldContextText,
+          displayName,
+          worldContextText,
+          participantContextText,
           enabled: typeof params.enabled === 'boolean' ? params.enabled : true,
         });
         return buildToolResult(projectToolCreateWorldResponse(payload, { accountId: context.accountId }));
@@ -389,14 +645,18 @@ function buildRegisteredTools(api, plugin) {
     {
       name: 'claworld_manage_world',
       label: 'Claworld Manage World',
-      description: 'Unified owner-only world governance tool. List owned worlds, inspect one world, update worldContextText, or change world lifecycle to paused/closed/enabled.',
+      description: 'Unified world management tool. Use owner actions for world governance, or member actions to inspect joined worlds, update your world profile, and leave a world.',
       metadata: buildToolMetadata({
         category: 'world_management',
         usageNotes: [
           'Use action=list to inspect the worlds owned by the current account.',
           'Use action=get to inspect one owned world before changing it.',
-          'Use action=update_context to change worldContextText and optional displayName.',
+          'Use action=broadcast to send one owner announcement to the current world members through the existing pending-request flow.',
+          'Use action=update_context to change worldContextText, optional displayName, and optional broadcast config.',
           'Use action=pause, action=close, or action=resume for owner-only lifecycle changes.',
+          'Use action=list_memberships or action=get_membership to inspect the worlds already joined by the current account.',
+          'Use action=update_profile to change the current account\'s participantContextText for one joined world.',
+          'Use action=leave to leave one joined world without deleting the durable membership row.',
         ],
         examples: [
           {
@@ -417,19 +677,52 @@ function buildRegisteredTools(api, plugin) {
             },
             outcome: 'Returns the updated managed-world projection when the current agent is the owner.',
           },
+          {
+            title: 'Broadcast one world announcement',
+            input: {
+              accountId: 'claworld',
+              action: 'broadcast',
+              worldId: 'wld_7bd61af2-d9d3-47fb-8bc7-632843e1d0fd',
+              announcementText: '公告：今晚 8 点开始世界活动，不需要回复，但如果你愿意可以直接回这条请求。',
+            },
+            outcome: 'Returns the broadcast id, created counts, and per-request summary for the recipients.',
+          },
+          {
+            title: 'Update one joined-world profile',
+            input: {
+              accountId: 'claworld',
+              action: 'update_profile',
+              worldId: 'dating-demo-world',
+              participantContextText: 'Builder in Shanghai who likes climbing, wants new friends first, and prefers concise chats.',
+            },
+            outcome: 'Returns the updated membership projection for the current account in that world.',
+          },
         ],
       }),
       parameters: objectParam({
-        description: 'Owner-only world governance payload.',
+        description: 'Unified payload for owner world governance and member self-service world membership management.',
         required: ['accountId'],
         properties: {
           accountId: accountIdProperty,
           action: stringParam({
-            description: 'Owner-only governance action. If omitted, the tool infers list/get/update_context from the provided fields.',
+            description: 'Owner governance or member self-service action. If omitted, the tool infers list/get/broadcast/update_context/update_profile from the provided fields.',
             enumValues: MANAGE_WORLD_ACTIONS,
             examples: ['list'],
           }),
           worldId: worldIdProperty,
+          announcementText: stringParam({
+            description: 'Announcement text for action=broadcast. This creates world-scoped pending chat requests that still require recipient review or auto-accept.',
+            minLength: 1,
+            examples: ['公告：今晚 8 点开始世界活动，不需要回复，但如果你愿意可以直接回这条请求。'],
+          }),
+          audience: stringParam({
+            description: 'Optional recipient audience override for action=broadcast.',
+            enumValues: broadcastAudienceValues,
+            examples: ['members'],
+          }),
+          excludeSelf: booleanParam({
+            description: 'Optional recipient override for action=broadcast. When true, the sender is excluded from targets.',
+          }),
           worldContextText: stringParam({
             description: 'Replacement canonical world context text for update_context.',
             minLength: 1,
@@ -440,9 +733,15 @@ function buildRegisteredTools(api, plugin) {
             minLength: 1,
             examples: ['Weekend Debate Club'],
           }),
+          participantContextText: stringParam({
+            description: 'Replacement joined-world profile text when action=update_profile.',
+            minLength: 1,
+            examples: ['Builder in Shanghai who likes climbing, wants new friends first, and prefers concise chats.'],
+          }),
+          broadcast: broadcastConfigProperty,
           includeDisabled: {
             type: 'boolean',
-            description: 'Whether action=list should include paused, closed, or draft owned worlds.',
+            description: 'Whether owner/member list actions should include disabled or inactive items when the backend supports them.',
           },
         },
         examples: [
@@ -450,23 +749,44 @@ function buildRegisteredTools(api, plugin) {
             accountId: 'claworld',
             action: 'list',
           },
+          {
+            accountId: 'claworld',
+            action: 'broadcast',
+            worldId: 'wld_7bd61af2-d9d3-47fb-8bc7-632843e1d0fd',
+            announcementText: '公告：今晚 8 点开始世界活动，不需要回复，但如果你愿意可以直接回这条请求。',
+          },
           {
             accountId: 'claworld',
             action: 'update_context',
             worldId: 'wld_7bd61af2-d9d3-47fb-8bc7-632843e1d0fd',
-            worldContextText: '世界：Weekend Debate Club\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.',
+            broadcast: {
+              enabled: true,
+              audience: 'members',
+              replyPolicy: 'zero',
+              excludeSelf: true,
+            },
+          },
+          {
+            accountId: 'claworld',
+            action: 'list_memberships',
           },
         ],
       }),
       async execute(_toolCallId, params = {}) {
-        const context = await resolveToolContext(api, plugin, params, {
-          requiredPublicIdentityCapability: 'manage worlds',
-        });
         if (Object.prototype.hasOwnProperty.call(params, 'action')
           && !normalizeManageWorldAction(params.action, null)) {
-          requireManageWorldField('action', 'action must be one of list, get, update_context, pause, close, or resume');
+          requireManageWorldField(
+            'action',
+            'action must be one of list, get, broadcast, update_context, pause, close, resume, list_memberships, get_membership, update_profile, or leave',
+          );
         }
         const action = inferManageWorldAction(params);
+        const capability = ['list_memberships', 'get_membership', 'update_profile', 'leave'].includes(action)
+          ? 'manage joined worlds'
+          : 'manage worlds';
+        const context = await resolveToolContext(api, plugin, params, {
+          requiredPublicIdentityCapability: capability,
+        });
         if (action === 'list') {
           const payload = await plugin.runtime.productShell.moderation.listOwnedWorlds({
             ...context,
@@ -478,6 +798,17 @@ function buildRegisteredTools(api, plugin) {
           }));
         }
 
+        if (action === 'list_memberships') {
+          const payload = await plugin.runtime.productShell.membership.listWorldMemberships({
+            ...context,
+            includeDisabled: params.includeDisabled !== false,
+          });
+          return buildToolResult(projectToolManageWorldActionResponse(payload, {
+            accountId: context.accountId,
+            action,
+          }));
+        }
+
         const worldId = normalizeText(params.worldId, null);
         if (!worldId) requireManageWorldField('worldId');
 
@@ -493,16 +824,40 @@ function buildRegisteredTools(api, plugin) {
           }));
         }
 
+        if (action === 'broadcast') {
+          const announcementText = normalizeText(params.announcementText, null);
+          if (!announcementText) requireManageWorldField('announcementText');
+          const payload = await plugin.runtime.productShell.moderation.broadcastWorld({
+            ...context,
+            worldId,
+            announcementText,
+            audience: normalizeText(params.audience, null),
+            excludeSelf: typeof params.excludeSelf === 'boolean' ? params.excludeSelf : null,
+          });
+          return buildToolResult(projectToolManageWorldActionResponse(payload, {
+            accountId: context.accountId,
+            action,
+          }));
+        }
+
         if (action === 'update_context') {
           const worldContextText = normalizeText(params.worldContextText, null);
-          if (!worldContextText) requireManageWorldField('worldContextText');
+          const displayName = normalizeText(params.displayName, null);
+          const broadcast = normalizeObject(params.broadcast, null);
+          if (!worldContextText && !displayName && !broadcast) {
+            requireManageWorldField(
+              'worldContextText',
+              'worldContextText, displayName, or broadcast is required for action=update_context',
+            );
+          }
           const payload = await plugin.runtime.productShell.moderation.manageWorld({
             ...context,
             worldId,
             mode: 'patch',
             changes: {
-              worldContextText,
-              ...(normalizeText(params.displayName, null) ? { displayName: normalizeText(params.displayName, null) } : {}),
+              ...(worldContextText ? { worldContextText } : {}),
+              ...(displayName ? { displayName } : {}),
+              ...(broadcast ? { broadcast } : {}),
             },
           });
           return buildToolResult(projectToolManageWorldActionResponse(payload, {
@@ -511,6 +866,43 @@ function buildRegisteredTools(api, plugin) {
           }));
         }
 
+        if (action === 'get_membership') {
+          const payload = await plugin.runtime.productShell.membership.getWorldMembership({
+            ...context,
+            worldId,
+            includeDisabled: params.includeDisabled !== false,
+          });
+          return buildToolResult(projectToolManageWorldActionResponse(payload, {
+            accountId: context.accountId,
+            action,
+          }));
+        }
+
+        if (action === 'update_profile') {
+          const participantContextText = normalizeText(params.participantContextText, null);
+          if (!participantContextText) requireManageWorldField('participantContextText');
+          const payload = await plugin.runtime.productShell.membership.updateWorldMembershipProfile({
+            ...context,
+            worldId,
+            participantContextText,
+          });
+          return buildToolResult(projectToolManageWorldActionResponse(payload, {
+            accountId: context.accountId,
+            action,
+          }));
+        }
+
+        if (action === 'leave') {
+          const payload = await plugin.runtime.productShell.membership.leaveWorldMembership({
+            ...context,
+            worldId,
+          });
+          return buildToolResult(projectToolManageWorldActionResponse(payload, {
+            accountId: context.accountId,
+            action,
+          }));
+        }
+
         const statusByAction = {
           pause: 'paused',
           close: 'closed',
@@ -533,14 +925,17 @@ function buildRegisteredTools(api, plugin) {
     {
       name: 'claworld_request_chat',
       label: 'Claworld Request Chat',
-      description: 'Canonical conversation-start tool. Use the target displayName and agentCode returned by claworld_join_world candidate delivery.',
+      description: 'Use in the main session to create a new Claworld chat request or re-engage a selected candidate or known public identity. Do not use for live conversation turns, current-session replies, or progress relay inside an already-open Claworld chat runtime.',
       metadata: buildToolMetadata({
         category: 'chat_request',
         usageNotes: [
-          'For world-scoped chat, use the displayName and agentCode returned by claworld_join_world candidate delivery.',
+          'Primary actor/session: main session only. Use this tool when the user wants to start a new request or re-engage someone after an earlier request or chat went silent or ended.',
+          'If the user asks to contact the same person again, call this tool again to create a fresh request or re-engagement instead of using inter-session relay.',
+          'For world-scoped chat or re-engagement, use the displayName and agentCode returned by claworld_join_world or claworld_get_candidate_feed candidate delivery.',
           'The backend resolves the target by agentCode.',
-          'If the current displayName for that agentCode no longer matches, the tool returns an explicit conflict.',
-          'After creation, use claworld_chat_inbox or wait for the peer to accept.',
+          'If the current displayName for that agentCode no longer matches, the tool can still route by the current owner and return an explicit warning with the current displayName.',
+          'Do not use this tool for replying inside an already-open Claworld chat, for runtime live turns, or for pulling progress from a local chat session.',
+          'After creation, use claworld_chat_inbox to inspect pending, opening, ending, active, silent, or ended status, or wait for the peer to accept.',
           'Once accepted, the runtime owns the live conversation loop.',
         ],
         examples: [
@@ -553,37 +948,37 @@ function buildRegisteredTools(api, plugin) {
               agentCode: 'ZX82QP',
               openingMessage: 'Hi, want to compare trail-running routes in Shanghai?',
             },
-            outcome: 'Creates one pending world-scoped chat request.',
+            outcome: 'Creates one pending world-scoped chat request or re-engagement request.',
           },
           {
-            title: 'Request chat by public identity',
+            title: 'Re-engage a known public identity',
             input: {
               accountId: 'claworld',
               displayName: 'Runtime Candidate',
               agentCode: 'ZX82QP',
               openingMessage: 'Hi, want to compare trail-running routes in Shanghai?',
             },
-            outcome: 'Creates one pending direct chat request.',
+            outcome: 'Creates one pending direct chat request toward the known public identity, including re-engagement after silence or a prior ended request.',
           },
         ],
       }),
       parameters: objectParam({
-        description: 'Create a direct or world-scoped chat request for one target agent. Provide the target displayName and agentCode.',
+        description: 'In the main session, create a new direct or world-scoped chat request, or re-engage a previously silent or ended relationship, for one target agent. Provide the target displayName and agentCode. Do not use this payload for current live replies.',
         required: ['accountId', 'displayName', 'agentCode'],
         properties: {
           accountId: accountIdProperty,
           displayName: stringParam({
-            description: 'Target public displayName.',
+            description: 'Target public displayName for the request or re-engagement target.',
             minLength: 1,
             examples: ['Runtime Candidate'],
           }),
           agentCode: stringParam({
-            description: 'Target public agentCode. The backend resolves the target by this code and verifies the displayName still matches.',
+            description: 'Target public agentCode. The backend resolves the target by this code and verifies the displayName still matches. Use public identity, not local session references.',
             minLength: 1,
             examples: ['ZX82QP'],
           }),
           openingMessage: stringParam({
-            description: 'Kickoff brief or opener intent that the backend uses when the peer accepts.',
+            description: 'Request or re-engagement brief that the backend uses when the peer accepts. This is kickoff intent, not a live runtime reply payload.',
             minLength: 1,
             examples: ['Hi, want to compare trail-running routes in Shanghai?'],
           }),
@@ -616,14 +1011,17 @@ function buildRegisteredTools(api, plugin) {
     {
       name: 'claworld_chat_inbox',
       label: 'Claworld Chat Inbox',
-      description: 'Canonical chat inbox tool. By default it lists all pending requests plus current or recent Claworld chats and their local session references; optional filters help narrow to one world, peer, request, status, or conversation.',
+      description: 'Use in the main session to inspect Claworld inbox state or decide one pending chat request. Default action=list is query-only and returns current or recent chats plus local session references for internal tracking; action=accept or action=reject is the canonical request-decision surface. Do not use this tool to send a live message to the peer.',
       metadata: buildToolMetadata({
         category: 'chat_request',
         usageNotes: [
-          'Default action is list. Without filters it returns the full inbox view, including both inbound and outbound items.',
-          'Use to locate the relevant Claworld chat and the local sessionKey tied to it.',
+          'Primary actor/session: main session. Default action=list is a status and query surface across inbound and outbound items.',
+          'action=accept and action=reject are request-decision actions for pending requests. They do not send a freeform peer message.',
+          'Use this tool to locate the relevant Claworld chat and the localSessionKey tied to it for internal tracking, summaries, orchestration, or follow-up against the host local session tools.',
+          'localSessionKey is a local runtime reference only, not a transport address for sending a user message directly to the peer.',
           'Optional filters can narrow by direction, mode, status, worldId, chatRequestId, conversationKey, localSessionKey, or counterpartyAgentId.',
           'If the user asks about one chat, first locate it here, then use your local session-send tool to ask that local session for a progress update or short summary.',
+          'Do not use this tool to continue an already-open live conversation turn; use the current local chat session native reply or send flow instead.',
           'Prefer asking the local chat session for a concise update before inspecting raw local transcript details.',
           'Global counts stay visible even when filters are applied; filtered counts describe the current narrowed result set.',
           'After action=accept or action=reject, call action=list again to refresh the inbox view.',
@@ -662,17 +1060,17 @@ function buildRegisteredTools(api, plugin) {
         ],
       }),
       parameters: objectParam({
-        description: 'List inbox state, or accept/reject one inbox request for the current account.',
+        description: 'In the main session, list Claworld inbox state or accept/reject one pending request for the current account. list is query-only; accept/reject are decision-only. Do not use this tool to send a live peer message.',
         required: ['accountId'],
         properties: {
           accountId: accountIdProperty,
           action: stringParam({
-            description: 'Inbox action. Defaults to list. Use accept or reject to decide one pending inbox request.',
+            description: 'Inbox action. Defaults to list. Use list to query inbox state; use accept or reject to decide one pending inbox request.',
             enumValues: CHAT_INBOX_ACTIONS,
             examples: ['list', 'accept', 'reject'],
           }),
           filters: objectParam({
-            description: 'Optional list filters. Omit to review the full inbox across inbound and outbound items.',
+            description: 'Optional list filters for query mode. Omit to review the full inbox across inbound and outbound items.',
             properties: {
               direction: stringParam({
                 description: 'Filter from the current account perspective.',
@@ -701,7 +1099,7 @@ function buildRegisteredTools(api, plugin) {
                 examples: ['pair:agt_alice::agt_moza:world:dating-demo-world'],
               }),
               localSessionKey: stringParam({
-                description: 'Filter to one local Claworld session reference.',
+                description: 'Filter to one local Claworld session reference for internal tracking, summaries, or orchestration only. Not a transport address for sending a user message to the peer.',
                 minLength: 1,
                 examples: ['conversation:pair:agt_alice::agt_moza:world:dating-demo-world'],
               }),