@xfxstudio/claworld 0.2.5 → 0.2.7

package/src/openclaw/plugin/register.js

@@ -1,8 +1,10 @@
 import { createClaworldChannelPlugin } from './claworld-channel-plugin.js';
 import {
-  projectToolChatRequestListResponse,
+  projectToolChatInboxResponse,
   projectToolChatRequestMutationResponse,
   projectToolCreateWorldResponse,
+  projectToolManagedWorldResponse,
+  projectToolOwnedWorldsResponse,
   projectToolWorldList,
   projectToolFeedbackSubmissionResponse,
   projectToolJoinWorldResponse,
@@ -17,6 +19,8 @@ import {
   normalizeRuntimeBoundaryError,
 } from '../../lib/runtime-errors.js';
 
+const INTERNAL_REQUESTER_SESSION_KEY_PARAM = '__claworldRequesterSessionKey';
+
 function normalizeText(value, fallback = null) {
   if (value == null) return fallback;
   const normalized = String(value).trim();
@@ -164,6 +168,7 @@ async function resolveToolContext(api, plugin, params = {}) {
       accountId,
       runtimeConfig,
       agentId: normalizeText(params.agentId, runtimeConfig.relay?.agentId || null),
+      requesterSessionKey: normalizeText(params[INTERNAL_REQUESTER_SESSION_KEY_PARAM], null),
     });
   }
 
@@ -173,6 +178,7 @@ async function resolveToolContext(api, plugin, params = {}) {
     accountId,
     runtimeConfig,
     agentId,
+    requesterSessionKey: normalizeText(params[INTERNAL_REQUESTER_SESSION_KEY_PARAM], null),
   };
 }
 
@@ -502,6 +508,120 @@ function buildRegisteredTools(api, plugin) {
         return buildToolResult(projectToolCreateWorldResponse(payload, { accountId: context.accountId }));
       },
     },
+    {
+      name: 'claworld_list_owned_worlds',
+      label: 'Claworld List Owned Worlds',
+      description: 'Owner-focused governance tool. List the worlds owned by the current account before choosing one to manage.',
+      metadata: buildToolMetadata({
+        category: 'world_management',
+        usageNotes: [
+          'Use when the user wants to inspect or pick from worlds they own.',
+          'This tool only returns owned worlds, not general directory worlds.',
+          'Pair this with claworld_manage_world for owner-only worldContext updates.',
+        ],
+        examples: [
+          {
+            title: 'List owned worlds',
+            input: {
+              accountId: 'claworld',
+            },
+            outcome: 'Returns owner-managed worlds for the current account.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Minimal payload for listing worlds owned by the current account.',
+        required: ['accountId'],
+        properties: {
+          accountId: accountIdProperty,
+          includeDisabled: {
+            type: 'boolean',
+            description: 'Whether to include disabled or draft owned worlds.',
+          },
+        },
+        examples: [
+          {
+            accountId: 'claworld',
+          },
+        ],
+      }),
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.runtime.productShell.moderation.listOwnedWorlds({
+          ...context,
+          includeDisabled: params.includeDisabled !== false,
+        });
+        return buildToolResult(projectToolOwnedWorldsResponse(payload, { accountId: context.accountId }));
+      },
+    },
+    {
+      name: 'claworld_manage_world',
+      label: 'Claworld Manage World',
+      description: 'Owner-only world management tool. Update the canonical worldContextText for one owner-managed world, with optional displayName/enabled changes.',
+      metadata: buildToolMetadata({
+        category: 'world_management',
+        usageNotes: [
+          'Use only when the current agent owns the target world.',
+          'This is the minimal management tool on the current public surface.',
+          'Prefer updating worldContextText directly instead of editing legacy world schema fields.',
+        ],
+        examples: [
+          {
+            title: 'Update one owned world context',
+            input: {
+              accountId: 'claworld',
+              worldId: 'ugc-weekend-debate-club',
+              worldContextText: '世界：Weekend Debate Club [ugc-weekend-debate-club]\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.',
+            },
+            outcome: 'Returns the updated managed-world projection when the current agent is the owner.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Minimal owner-only world management payload.',
+        required: ['accountId', 'worldId', 'worldContextText'],
+        properties: {
+          accountId: accountIdProperty,
+          worldId: worldIdProperty,
+          worldContextText: stringParam({
+            description: 'Replacement canonical world context text for the owned world.',
+            minLength: 1,
+            examples: ['世界：Weekend Debate Club [ugc-weekend-debate-club]\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.'],
+          }),
+          displayName: stringParam({
+            description: 'Optional new display name for the owned world.',
+            minLength: 1,
+            examples: ['Weekend Debate Club'],
+          }),
+          enabled: {
+            type: 'boolean',
+            description: 'Optional enabled flag for the owned world.',
+          },
+        },
+        examples: [
+          {
+            accountId: 'claworld',
+            worldId: 'ugc-weekend-debate-club',
+            worldContextText: '世界：Weekend Debate Club [ugc-weekend-debate-club]\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.',
+          },
+        ],
+      }),
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const changes = {
+          worldContextText: params.worldContextText,
+          ...(params.displayName ? { displayName: params.displayName } : {}),
+        };
+        const payload = await plugin.runtime.productShell.moderation.manageWorld({
+          ...context,
+          worldId: params.worldId,
+          mode: 'patch',
+          changes,
+          ...(Object.prototype.hasOwnProperty.call(params, 'enabled') ? { enabled: params.enabled === true } : {}),
+        });
+        return buildToolResult(projectToolManagedWorldResponse(payload, { accountId: context.accountId }));
+      },
+    },
     {
       name: 'claworld_request_chat',
       label: 'Claworld Request Chat',
@@ -510,7 +630,7 @@ function buildRegisteredTools(api, plugin) {
         category: 'chat_request',
         usageNotes: [
           'For world-scoped chat, use the targetAgentId returned by claworld_join_world.',
-          'After creation, use claworld_list_chat_requests or wait for the peer to accept.',
+          'After creation, use claworld_chat_inbox or wait for the peer to accept.',
           'Once accepted, the runtime owns the live conversation loop.',
         ],
         examples: [
@@ -564,33 +684,36 @@ function buildRegisteredTools(api, plugin) {
       },
     },
     {
-      name: 'claworld_list_chat_requests',
-      label: 'Claworld List Chat Requests',
-      description: 'Canonical review tool for pending chat requests after request_chat or before accept_chat_request.',
+      name: 'claworld_chat_inbox',
+      label: 'Claworld Chat Inbox',
+      description: 'Canonical chat inbox tool. Review pending requests plus current or recent Claworld chats and the local session references you can use to check progress.',
       metadata: buildToolMetadata({
         category: 'chat_request',
         usageNotes: [
-          'Use to review inbound requests waiting for acceptance.',
-          'Use direction=outbound when checking whether a previously-created request is still pending.',
+          'Use to review pending inbound requests waiting for acceptance.',
+          'Use to locate the relevant Claworld chat and the local sessionKey tied to it.',
+          '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.',
+          'Prefer asking the local chat session for a concise update before inspecting raw local transcript details.',
+          'Use direction=outbound when focusing on chats you initiated.',
         ],
         examples: [
           {
-            title: 'Review inbound requests',
+            title: 'Review inbound chat state',
             input: {
               accountId: 'claworld',
               direction: 'inbound',
             },
-            outcome: 'Returns the current pending or accepted chat requests for the current account.',
+            outcome: 'Returns pending requests plus related chats for the current account.',
           },
         ],
       }),
       parameters: objectParam({
-        description: 'List direct or world-scoped chat requests for the current account.',
+        description: 'Review overall Claworld chat state for the current account before deciding whether to accept a request or query one local chat session for progress.',
         required: ['accountId'],
         properties: {
           accountId: accountIdProperty,
           direction: stringParam({
-            description: 'Filter to inbound requests you can review or outbound requests you previously created.',
+            description: 'Filter to inbound or outbound chat state from the current account perspective.',
             enumValues: ['inbound', 'outbound'],
             examples: ['inbound'],
           }),
@@ -604,11 +727,11 @@ function buildRegisteredTools(api, plugin) {
       }),
       async execute(_toolCallId, params = {}) {
         const context = await resolveToolContext(api, plugin, params);
-        const payload = await plugin.helpers.social.listChatRequests({
+        const payload = await plugin.helpers.social.listChatInbox({
           ...context,
           direction: params.direction || null,
         });
-        return buildToolResult(projectToolChatRequestListResponse(payload, { accountId: context.accountId }));
+        return buildToolResult(projectToolChatInboxResponse(payload, { accountId: context.accountId }));
       },
     },
     {
@@ -618,7 +741,7 @@ function buildRegisteredTools(api, plugin) {
       metadata: buildToolMetadata({
         category: 'chat_request',
         usageNotes: [
-          'Use the chatRequestId returned by claworld_list_chat_requests.',
+          'Use the chatRequestId returned by claworld_chat_inbox pendingRequests.',
           'After acceptance, do not try to send a separate raw message tool call; wait for runtime-owned live conversation.',
         ],
         examples: [
@@ -638,7 +761,7 @@ function buildRegisteredTools(api, plugin) {
         properties: {
           accountId: accountIdProperty,
           chatRequestId: stringParam({
-            description: 'Canonical chat request id returned by claworld_list_chat_requests.',
+            description: 'Canonical chat request id returned by claworld_chat_inbox pendingRequests.',
             minLength: 1,
             examples: ['req_demo_1'],
           }),
@@ -891,6 +1014,19 @@ export function registerClaworldPluginFull(api, plugin) {
   if (!plugin) {
     throw new Error('registerClaworldPluginFull requires a plugin instance');
   }
+  if (typeof api.on === 'function') {
+    api.on('before_tool_call', async (event, ctx) => {
+      if (event?.toolName !== 'claworld_request_chat') return;
+      const requesterSessionKey = normalizeText(ctx?.sessionKey, null);
+      if (!requesterSessionKey) return;
+      return {
+        params: {
+          ...(event?.params && typeof event.params === 'object' && !Array.isArray(event.params) ? event.params : {}),
+          [INTERNAL_REQUESTER_SESSION_KEY_PARAM]: requesterSessionKey,
+        },
+      };
+    });
+  }
   if (typeof api.registerHttpRoute === 'function') {
     api.registerHttpRoute(buildClaworldStatusRoute(plugin));
   }