@xfxstudio/claworld 2026.4.30-testing.3 → 2026.5.3-testing.1

package/src/openclaw/plugin/register.js

@@ -18,6 +18,7 @@ import {
   buildClaworldToolMaintenanceEvent,
   ensureClaworldWorkingMemory,
   resolveClaworldBootstrapTarget,
+  updateClaworldSessionDirectory,
 } from '../runtime/working-memory.js';
 import { resolveOpenClawWorkspaceRoot } from '../runtime/workspace-resolver.js';
 import { setClaworldRuntime } from './runtime.js';
@@ -142,6 +143,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 +320,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 +1063,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 +1095,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 +1855,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.',
@@ -2095,13 +2225,45 @@ export function registerClaworldPluginFull(api, plugin) {
     });
 
     api.on('before_tool_call', async (event, ctx) => {
-      if (event?.toolName !== 'claworld_manage_conversations') return;
+      const toolName = normalizeText(event?.toolName, null);
+      if (!toolName || !toolName.startsWith('claworld_')) return;
       const params = event?.params && typeof event.params === 'object' && !Array.isArray(event.params)
         ? event.params
         : {};
-      if (normalizeTerminalConversationAction(params.action, null) !== 'request') return;
       const requesterSessionKey = normalizeText(ctx?.sessionKey, null);
-      if (!requesterSessionKey) return;
+      if (requesterSessionKey) {
+        const logger = getHookLogger(api);
+        try {
+          const workspaceRoot = await resolveHookWorkspaceRoot(api, event, ctx);
+          if (workspaceRoot) {
+            await updateClaworldSessionDirectory(
+              workspaceRoot,
+              {
+                timestamp: event?.timestamp || ctx?.timestamp || null,
+                source: 'claworld_hook',
+                eventType: 'before_tool_call',
+                kind: toolName,
+                toolName,
+                relations: {
+                  localSessionKey: requesterSessionKey,
+                  sessionKey: requesterSessionKey,
+                  localAgentId: normalizeText(ctx?.agentId ?? ctx?.AgentId, null),
+                },
+                context: ctx || {},
+              },
+            );
+          }
+        } catch (error) {
+          logger?.warn?.('[claworld:working-memory] unable to update session directory before tool call', error);
+        }
+      }
+      if (
+        toolName !== 'claworld_manage_conversations'
+        || normalizeTerminalConversationAction(params.action, null) !== 'request'
+        || !requesterSessionKey
+      ) {
+        return;
+      }
       return {
         params: {
           ...params,
@@ -2123,6 +2285,7 @@ export function registerClaworldPluginFull(api, plugin) {
           params: event?.params || {},
           result: hookToolResult(event),
           timestamp: event?.timestamp || ctx?.timestamp || null,
+          context: ctx || {},
         });
         if (!maintenanceEvent) return;
         await appendClaworldJournalEvent(workspaceRoot, maintenanceEvent);

package/src/openclaw/plugin/relay-client-shared.js

@@ -95,13 +95,23 @@ export function buildInboundEnvelope(message = {}) {
       'text',
       'body',
       'notification',
+      'conversationKey',
+      'worldId',
     ]) {
       if (payload[key] == null && data[key] != null) payload[key] = data[key];
     }
   }
+  const notification = payload.notification && typeof payload.notification === 'object' && !Array.isArray(payload.notification)
+    ? payload.notification
+    : data.notification && typeof data.notification === 'object' && !Array.isArray(data.notification)
+      ? data.notification
+      : {};
   const targetAgentId = normalizeEnvelopeText(
     data.targetAgentId,
-    normalizeEnvelopeText(payload.targetAgentId, null),
+    normalizeEnvelopeText(
+      payload.targetAgentId,
+      normalizeEnvelopeText(notification.targetAgentId, normalizeEnvelopeText(metadata.targetAgentId, null)),
+    ),
   );
   const sessionKey = normalizeEnvelopeText(
     data.sessionKey,
@@ -109,23 +119,48 @@ export function buildInboundEnvelope(message = {}) {
       payload.sessionKey,
       normalizeEnvelopeText(
         data.targetSessionKey,
-        normalizeEnvelopeText(payload.targetSessionKey, null),
+        normalizeEnvelopeText(
+          payload.targetSessionKey,
+          normalizeEnvelopeText(
+            notification.targetSessionKey,
+            normalizeEnvelopeText(metadata.sessionKey, targetAgentId ? `management:${targetAgentId}` : null),
+          ),
+        ),
       ),
     ),
   );
   const isDeliveryEvent = message.event === 'delivery';
   const isRoutableEvent = Boolean(eventType && sessionKey);
   if (!isDeliveryEvent && !isRoutableEvent) return null;
+  const deliveryId = resolveEnvelopeMessageId(data, payload);
+  const eventName = normalizeEnvelopeText(
+    data.eventName,
+    normalizeEnvelopeText(payload.eventName, isDeliveryEvent ? null : normalizeEnvelopeText(message.event, null)),
+  );
   return {
     eventType: eventType || 'delivery',
-    deliveryId: resolveEnvelopeMessageId(data, payload),
+    eventName,
+    eventId: deliveryId,
+    deliveryId,
     sessionKey,
     targetAgentId,
-    createdAt: data.createdAt || data.availableAt || null,
-    updatedAt: data.updatedAt || null,
+    conversationKey: normalizeEnvelopeText(
+      data.conversationKey,
+      normalizeEnvelopeText(payload.conversationKey, normalizeEnvelopeText(notification.relatedObjects?.conversationKey, null)),
+    ),
+    worldId: normalizeEnvelopeText(
+      data.worldId,
+      normalizeEnvelopeText(payload.worldId, normalizeEnvelopeText(notification.relatedObjects?.worldId, null)),
+    ),
+    createdAt: data.createdAt || payload.createdAt || data.availableAt || payload.availableAt || notification.createdAt || null,
+    updatedAt: data.updatedAt || payload.updatedAt || notification.updatedAt || null,
     turnCreatedAt: data.turnCreatedAt || null,
     payload,
-    metadata,
+    metadata: {
+      ...metadata,
+      relayEvent: normalizeEnvelopeText(message.event, null),
+      inboxItemId: normalizeEnvelopeText(data.inboxItemId, normalizeEnvelopeText(payload.inboxItemId, null)),
+    },
   };
 }
 

package/src/openclaw/protocol/relay-event-protocol.js

@@ -1,6 +1,15 @@
 export const CLAWORLD_PLUGIN_BRIDGE_PROTOCOL = 'claworld.delivery_reply.v1';
 
 const DELIVERY_EVENT_TYPE = 'delivery';
+const MANAGEMENT_EVENT_TYPES = new Set([
+  'notification',
+  'domain_notification',
+  'management_wake',
+  'management_tick',
+  'conversation_lifecycle',
+  'platform_recommendation',
+  'ops_recommendation',
+]);
 
 function normalizeText(value, fallback = null) {
   if (value == null) return fallback;
@@ -16,27 +25,28 @@ function normalizePayload(payload = null) {
 export function createRelayEventProtocol() {
   return {
     version: CLAWORLD_PLUGIN_BRIDGE_PROTOCOL,
-    eventTypes: [DELIVERY_EVENT_TYPE],
-    requiredEnvelopeFields: ['eventType', 'deliveryId', 'sessionKey', 'payload'],
+    eventTypes: [DELIVERY_EVENT_TYPE, ...MANAGEMENT_EVENT_TYPES],
+    requiredEnvelopeFields: ['eventType', 'sessionKey', 'payload'],
     describeEvent(event = {}) {
       const payload = normalizePayload(event.payload);
       const missing = [];
-      if (normalizeText(event.eventType, null) !== DELIVERY_EVENT_TYPE) {
+      const eventType = normalizeText(event.eventType, null);
+      if (eventType !== DELIVERY_EVENT_TYPE && !MANAGEMENT_EVENT_TYPES.has(eventType)) {
         missing.push('eventType');
       }
-      if (!normalizeText(event.deliveryId, null)) {
+      if (eventType === DELIVERY_EVENT_TYPE && !normalizeText(event.deliveryId, null)) {
         missing.push('deliveryId');
       }
       if (!normalizeText(event.sessionKey, null)) {
         missing.push('sessionKey');
       }
-      if (!normalizeText(payload.text, null)) {
+      if (eventType === DELIVERY_EVENT_TYPE && !normalizeText(payload.text, null)) {
         missing.push('payload.text');
       }
       return {
         ok: missing.length === 0,
         missing,
-        role: 'delivery',
+        role: eventType === DELIVERY_EVENT_TYPE ? 'delivery' : 'management',
       };
     },
   };