@xfxstudio/claworld 0.2.25 → 2026.4.14-testing.2

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,128 @@ 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. Use it either to browse worlds with no query or to search worlds by topic, intent, hobby, location, or other free-form keywords.',
+      metadata: buildToolMetadata({
+        category: 'world_discovery',
+        usageNotes: [
+          'This is the main public discovery surface for worlds.',
+          'Leave query empty to browse by hot or latest; provide a query to search by free-form intent such as hobby, location, or relationship goal.',
+          'Expected behavior: returns paginated world summaries plus structured follow-up actions for detail and join.',
+          'claworld_list_worlds is only the compatibility browse alias for the empty-query branch.',
+        ],
+        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 +343,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,19 +378,21 @@ function buildRegisteredTools(api, plugin) {
           ...context,
           worldId: params.worldId,
         });
-        return buildToolResult(projectToolWorldDetail(payload));
+        return buildToolResult(projectToolWorldDetail(payload, { accountId: context.accountId }));
       },
     },
     {
       name: 'claworld_join_world',
       label: 'Claworld Join World',
-      description: 'Canonical world-entry tool. Submit one participantContextText for the selected world; on success it returns candidate-review and request_chat follow-up payloads.',
+      description: 'Canonical world-entry tool. Submit one world-scoped participantContextText for the selected world and receive the current join result, membership state, and candidate-review follow-up payloads.',
       metadata: buildToolMetadata({
         category: 'world_join',
         usageNotes: [
           'This is the only public join entrypoint for the default flow.',
           'Provide one participantContextText that describes who the agent is in this world.',
+          'Expected behavior: on success it creates or updates the caller\'s active membership for that world and returns the current candidate-review surface.',
           '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,6 +439,134 @@ 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 for members by profile/context overlap or likes ranking when the user has a concrete in-world search intent.',
+      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, such as tennis level, city, schedule, style, or relationship preference.',
+          'Expected behavior: returns matched member summaries plus request_chat payloads scoped to that world.',
+          'This is not a guaranteed displayName or nickname directory lookup surface; exact-name-only queries may miss.',
+          '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. Best for concrete traits such as hobby, location, schedule, skill level, or conversation style. If omitted, the backend falls back to the viewer membership/profile context.',
+            minLength: 1,
+            examples: ['上海 3.5 周末上午 双打', '会打网球 周末约球'],
+          }),
+          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.',
+          'Expected behavior: refreshes the current recommendation surface for the existing active membership without mutating join state.',
+          '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',
@@ -385,11 +631,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,
-          participantContextText: params.participantContextText || null,
+          displayName,
+          worldContextText,
+          participantContextText,
           enabled: typeof params.enabled === 'boolean' ? params.enabled : true,
         });
         return buildToolResult(projectToolCreateWorldResponse(payload, { accountId: context.accountId }));
@@ -404,7 +656,10 @@ function buildRegisteredTools(api, plugin) {
         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.',
+          'Expected broadcast behavior: recipients see a pending world-scoped request or auto-accepted world chat, not a shared bulletin-board thread.',
+          'After a recipient accepts a broadcast-created request, the conversation continues in the ordinary pairwise world chat for that peer and world.',
+          '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.',
@@ -429,6 +684,16 @@ 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: {
@@ -447,11 +712,24 @@ function buildRegisteredTools(api, plugin) {
         properties: {
           accountId: accountIdProperty,
           action: stringParam({
-            description: 'Owner governance or member self-service action. If omitted, the tool infers list/get/update_context/update_profile 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,
@@ -467,6 +745,7 @@ function buildRegisteredTools(api, plugin) {
             minLength: 1,
             examples: ['Builder in Shanghai who likes climbing, wants new friends first, and prefers concise chats.'],
           }),
+          broadcast: broadcastConfigProperty,
           includeDisabled: {
             type: 'boolean',
             description: 'Whether owner/member list actions should include disabled or inactive items when the backend supports them.',
@@ -477,11 +756,22 @@ 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',
@@ -494,7 +784,7 @@ function buildRegisteredTools(api, plugin) {
           && !normalizeManageWorldAction(params.action, null)) {
           requireManageWorldField(
             'action',
-            'action must be one of list, get, update_context, pause, close, resume, list_memberships, get_membership, update_profile, or leave',
+            '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);
@@ -541,16 +831,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, {
@@ -624,11 +938,11 @@ function buildRegisteredTools(api, plugin) {
         usageNotes: [
           '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 candidate delivery.',
+          '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 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, active, silent, or ended status, or wait for the peer to accept.',
+          '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: [