@xfxstudio/claworld 2026.4.29-testing.2 → 2026.4.29-testing.3

package/openclaw.plugin.json

@@ -8,7 +8,7 @@
   ],
   "name": "Claworld Persona Relay",
   "description": "Claworld relay world channel plugin for OpenClaw.",
-  "version": "2026.4.29-testing.2",
+  "version": "2026.4.29-testing.3",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

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

package/src/openclaw/plugin/register.js

@@ -142,6 +142,33 @@ const CHAT_INBOX_FILTER_STATUSES = Object.freeze([
   'kickoff_failed',
   'ended',
 ]);
+const CHAT_INBOX_FILTER_KEYS = Object.freeze([
+  'direction',
+  'mode',
+  'status',
+  'worldId',
+  'chatRequestId',
+  'conversationKey',
+  'localSessionKey',
+  'counterpartyAgentId',
+]);
+const CHAT_INBOX_FILTER_KEY_SET = new Set(CHAT_INBOX_FILTER_KEYS);
+const MANAGE_CONVERSATION_REQUEST_ONLY_QUERY_FIELDS = Object.freeze([
+  'displayName',
+  'agentCode',
+  'openingMessage',
+]);
+const MANAGE_CONVERSATION_FILTER_ONLY_TOP_LEVEL_FIELDS = Object.freeze([
+  'mode',
+  'status',
+  'worldId',
+  'counterpartyAgentId',
+]);
+const MANAGE_CONVERSATION_GET_STATE_TARGET_FIELDS = Object.freeze([
+  'chatRequestId',
+  'conversationKey',
+  'localSessionKey',
+]);
 
 const TERMINAL_ACCOUNT_ACTIONS = Object.freeze([
   'view_account',
@@ -292,6 +319,117 @@ function normalizeChatInboxListFiltersInput(params = {}) {
   );
 }
 
+function hasProvidedToolParam(params = {}, fieldId) {
+  if (!params || typeof params !== 'object') return false;
+  if (!Object.prototype.hasOwnProperty.call(params, fieldId)) return false;
+  const value = params[fieldId];
+  if (typeof value === 'string') return normalizeText(value, null) != null;
+  return value != null;
+}
+
+function buildChatInboxFiltersParam({ description, worldIdProperty } = {}) {
+  return objectParam({
+    description,
+    additionalProperties: false,
+    properties: {
+      direction: stringParam({
+        description: 'Filter from the current account perspective.',
+        enumValues: CHAT_INBOX_FILTER_DIRECTIONS,
+        examples: ['outbound'],
+      }),
+      mode: stringParam({
+        description: 'Filter to direct or world-scoped chat items.',
+        enumValues: CHAT_INBOX_FILTER_MODES,
+        examples: ['world'],
+      }),
+      status: stringParam({
+        description: 'Filter to pending or terminal requests, or to chats by current status.',
+        enumValues: CHAT_INBOX_FILTER_STATUSES,
+        examples: ['active'],
+      }),
+      worldId: worldIdProperty,
+      chatRequestId: stringParam({
+        description: 'Filter to one canonical chat request id.',
+        minLength: 1,
+        examples: ['req_demo_1'],
+      }),
+      conversationKey: stringParam({
+        description: 'Filter to one canonical conversation key.',
+        minLength: 1,
+        examples: ['pair:agt_alice::agt_moza:world:dating-demo-world'],
+      }),
+      localSessionKey: stringParam({
+        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'],
+      }),
+      counterpartyAgentId: stringParam({
+        description: 'Filter to one counterparty agentId.',
+        minLength: 1,
+        examples: ['agt_alice'],
+      }),
+    },
+  });
+}
+
+function validateChatInboxFilterInput(filters = {}, action) {
+  const source = normalizeObject(filters, {}) || {};
+  for (const key of Object.keys(source)) {
+    if (CHAT_INBOX_FILTER_KEY_SET.has(key)) continue;
+    requireManageWorldField(`filters.${key}`, `filters.${key} is not supported for action=${action}`);
+  }
+  return source;
+}
+
+function normalizeManageConversationInboxQuery(params = {}, action) {
+  const normalizedAction = normalizeTerminalConversationAction(action, 'list_related');
+  const filters = validateChatInboxFilterInput(params.filters, normalizedAction);
+
+  const requestOnlyField = MANAGE_CONVERSATION_REQUEST_ONLY_QUERY_FIELDS.find((fieldId) => hasProvidedToolParam(params, fieldId));
+  if (requestOnlyField) {
+    requireManageWorldField(requestOnlyField, `${requestOnlyField} is only supported for action=request`);
+  }
+  if (hasProvidedToolParam(params, 'limit')) {
+    requireManageWorldField('limit', `limit is not supported for action=${normalizedAction}`);
+  }
+
+  const filterOnlyField = MANAGE_CONVERSATION_FILTER_ONLY_TOP_LEVEL_FIELDS.find((fieldId) => hasProvidedToolParam(params, fieldId));
+  if (filterOnlyField) {
+    requireManageWorldField(
+      filterOnlyField,
+      `${filterOnlyField} must be passed as filters.${filterOnlyField} for action=${normalizedAction}`,
+    );
+  }
+
+  if (normalizedAction !== 'get_state') {
+    const getStateOnlyField = MANAGE_CONVERSATION_GET_STATE_TARGET_FIELDS.find((fieldId) => hasProvidedToolParam(params, fieldId));
+    if (getStateOnlyField) {
+      requireManageWorldField(
+        getStateOnlyField,
+        `${getStateOnlyField} must be passed as filters.${getStateOnlyField} for action=${normalizedAction}`,
+      );
+    }
+  }
+
+  const mergedFilters = {
+    ...filters,
+    ...(!Object.prototype.hasOwnProperty.call(filters, 'direction') && hasProvidedToolParam(params, 'direction')
+      ? { direction: params.direction }
+      : {}),
+    ...(normalizedAction === 'get_state'
+      ? Object.fromEntries(
+          MANAGE_CONVERSATION_GET_STATE_TARGET_FIELDS
+            .filter((fieldId) => (
+              !Object.prototype.hasOwnProperty.call(filters, fieldId)
+              && hasProvidedToolParam(params, fieldId)
+            ))
+            .map((fieldId) => [fieldId, params[fieldId]]),
+        )
+      : {}),
+  };
+  return normalizeChatInboxListFiltersInput({ filters: mergedFilters });
+}
+
 function parseToolResultPayload(result = null) {
   const text = result?.content?.[0]?.text;
   if (typeof text !== 'string') return null;
@@ -924,10 +1062,27 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
           agentCode: stringParam({ description: 'Target public agent code for request.', minLength: 1 }),
           openingMessage: stringParam({ description: 'Request/re-engagement kickoff message.', minLength: 1 }),
           worldId: worldIdProperty,
-          filters: objectParam({ description: 'List filters.', additionalProperties: true }),
-          chatRequestId: stringParam({ description: 'Request id for accept/reject.', minLength: 1 }),
-          conversationKey: stringParam({ description: 'Conversation key for get_state/close.', minLength: 1 }),
-          localSessionKey: stringParam({ description: 'Local conversation session key for get_state/close.', minLength: 1 }),
+          direction: stringParam({
+            description: 'Top-level alias for filters.direction on action=list_related/get_state.',
+            enumValues: CHAT_INBOX_FILTER_DIRECTIONS,
+            examples: ['outbound'],
+          }),
+          filters: buildChatInboxFiltersParam({
+            description: 'Inbox filters for action=list_related/get_state.',
+            worldIdProperty,
+          }),
+          chatRequestId: stringParam({
+            description: 'Request id for action=accept/reject, or a top-level get_state convenience target that normalizes to filters.chatRequestId.',
+            minLength: 1,
+          }),
+          conversationKey: stringParam({
+            description: 'Conversation key for action=close, or a top-level get_state convenience target that normalizes to filters.conversationKey.',
+            minLength: 1,
+          }),
+          localSessionKey: stringParam({
+            description: 'Local conversation session key for action=close, or a top-level get_state convenience target that normalizes to filters.localSessionKey.',
+            minLength: 1,
+          }),
         },
       }),
       async execute(toolCallId, params = {}) {
@@ -939,10 +1094,19 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
           });
           return rewriteToolResultName(result, manageConversationsTool, action);
         }
-        if (['list_related', 'get_state', 'accept', 'reject'].includes(action)) {
+        if (action === 'list_related' || action === 'get_state') {
+          const filters = normalizeManageConversationInboxQuery(params, action);
           const result = await requireTerminalTool(internalTools, 'claworld_chat_inbox').execute(toolCallId, {
             ...params,
-            action: ['list_related', 'get_state'].includes(action) ? 'list' : action,
+            action: 'list',
+            ...(Object.keys(filters).length > 0 ? { filters } : {}),
+          });
+          return rewriteToolResultName(result, manageConversationsTool, action);
+        }
+        if (action === 'accept' || action === 'reject') {
+          const result = await requireTerminalTool(internalTools, 'claworld_chat_inbox').execute(toolCallId, {
+            ...params,
+            action,
           });
           return rewriteToolResultName(result, manageConversationsTool, action);
         }
@@ -1690,45 +1854,10 @@ function buildRegisteredTools(api, plugin) {
             examples: ['list', 'accept', 'reject'],
           }),
           filters: objectParam({
-            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.',
-                enumValues: CHAT_INBOX_FILTER_DIRECTIONS,
-                examples: ['outbound'],
-              }),
-              mode: stringParam({
-                description: 'Filter to direct or world-scoped chat items.',
-                enumValues: CHAT_INBOX_FILTER_MODES,
-                examples: ['world'],
-              }),
-              status: stringParam({
-                description: 'Filter to pending or terminal requests, or to chats by current status.',
-                enumValues: CHAT_INBOX_FILTER_STATUSES,
-                examples: ['active'],
-              }),
-              worldId: worldIdProperty,
-              chatRequestId: stringParam({
-                description: 'Filter to one canonical chat request id.',
-                minLength: 1,
-                examples: ['req_demo_1'],
-              }),
-              conversationKey: stringParam({
-                description: 'Filter to one canonical conversation key.',
-                minLength: 1,
-                examples: ['pair:agt_alice::agt_moza:world:dating-demo-world'],
-              }),
-              localSessionKey: stringParam({
-                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'],
-              }),
-              counterpartyAgentId: stringParam({
-                description: 'Filter to one counterparty agentId.',
-                minLength: 1,
-                examples: ['agt_alice'],
-              }),
-            },
+            ...buildChatInboxFiltersParam({
+              description: 'Optional list filters for query mode. Omit to review the full inbox across inbound and outbound items.',
+              worldIdProperty,
+            }),
           }),
           chatRequestId: stringParam({
             description: 'Canonical chat request id returned by claworld_chat_inbox pendingRequests. Required for action=accept or action=reject.',