@xfxstudio/claworld 2026.4.29-testing.3 → 2026.4.30-pr190-feature.1

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.3",
+  "version": "2026.4.30-pr190-feature.1",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

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

package/src/lib/chat-request.js

@@ -1,6 +1,8 @@
 import { createKickoffBrief } from './relay/kickoff-text.js';
 import { normalizeAcceptedChatKickoffRecord } from './relay/kickoff-progress.js';
 
+export const DEFAULT_CHAT_REQUEST_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
 function normalizeText(value, fallback = null) {
   if (value == null) return fallback;
   const normalized = String(value).trim();

package/src/openclaw/plugin/claworld-channel-plugin.js

@@ -132,6 +132,35 @@ function resolveNormalizedText(value, fallback = null) {
   return normalizeClaworldText(value, fallback);
 }
 
+function resolveInboundMessageId({ delivery = {}, payload = {}, metadata = {} } = {}) {
+  const notification = payload.notification && typeof payload.notification === 'object' && !Array.isArray(payload.notification)
+    ? payload.notification
+    : delivery.notification && typeof delivery.notification === 'object' && !Array.isArray(delivery.notification)
+      ? delivery.notification
+      : {};
+  const candidates = [
+    delivery.deliveryId,
+    delivery.inboxItemId,
+    delivery.messageId,
+    delivery.eventId,
+    delivery.notificationId,
+    payload.deliveryId,
+    payload.inboxItemId,
+    payload.messageId,
+    payload.eventId,
+    payload.notificationId,
+    metadata.messageId,
+    metadata.eventId,
+    metadata.notificationId,
+    notification.notificationId,
+  ];
+  for (const candidate of candidates) {
+    const normalized = resolveNormalizedText(candidate, null);
+    if (normalized) return normalized;
+  }
+  return null;
+}
+
 function isAgentScopedSessionKey(sessionKey) {
   return /^agent:[^:]+:/i.test(String(sessionKey || ''));
 }
@@ -274,6 +303,7 @@ function parseBridgeTimestampMs(value) {
 
 function resolveBridgeDeliveryTimestampMs({ delivery = {}, metadata = {} } = {}) {
   return parseBridgeTimestampMs(delivery?.createdAt)
+    || parseBridgeTimestampMs(delivery?.availableAt)
     || parseBridgeTimestampMs(delivery?.turnCreatedAt)
     || parseBridgeTimestampMs(metadata?.createdAt)
     || Date.now();
@@ -1752,6 +1782,7 @@ function buildDeliveryInboundEnvelope({
   commandText = null,
   timestamp = null,
   deliveryId,
+  eventType = 'delivery',
   sessionKey,
   localSessionKey = null,
   worldId = null,
@@ -1770,13 +1801,16 @@ function buildDeliveryInboundEnvelope({
   const normalizedCommandText = String(commandText || '').trim();
   const commandBody = normalizedCommandText || rawBody;
   const bodyForAgent = bodyText || rawBody;
+  const eventLabel = normalizePluginOptionalText(eventType) === 'delivery'
+    ? 'delivery'
+    : `event ${normalizePluginOptionalText(eventType)}`;
   const contextLines = mergeUntrustedContextLines([
     `[claworld peer ${remoteLabel}]`,
     ...(worldId ? [`[claworld world ${worldId}]`] : []),
     ...(conversationKey ? [`[claworld conversation ${conversationKey}]`] : []),
     ...(localSessionKey && localSessionKey !== sessionKey ? [`[claworld local session ${localSessionKey}]`] : []),
     `[claworld relay session ${sessionKey}]`,
-    `[claworld delivery ${deliveryId}]`,
+    `[claworld ${eventLabel} ${deliveryId}]`,
   ], untrustedContext);
   const envelopeTimestamp = Number.isFinite(timestamp) ? new Date(timestamp) : new Date();
 
@@ -2173,7 +2207,7 @@ function resolveBoundLocalAgentId({ cfg = {}, runtimeConfig = {}, relayClient }
     || 'main';
 }
 
-async function maybeBridgeRuntimeDelivery({
+async function maybeBridgeRuntimeInboundEvent({
   relayClient,
   runtimeConfig,
   runtimeAccountId,
@@ -2192,36 +2226,46 @@ async function maybeBridgeRuntimeDelivery({
   const payload = delivery.payload && typeof delivery.payload === 'object' && !Array.isArray(delivery.payload)
     ? delivery.payload
     : {};
-  const deliveryId = resolveNormalizedText(delivery.deliveryId, null);
+  const eventType = resolveNormalizedText(delivery.eventType, resolveNormalizedText(event?.eventType, 'delivery'));
+  const deliveryId = resolveInboundMessageId({ delivery, payload, metadata });
   const sessionKey = resolveNormalizedText(delivery.sessionKey, null);
   const contextText = resolveNormalizedText(payload.contextText, null);
   const incomingText = resolveNormalizedText(
     payload.commandText,
-    contextText ? null : resolveNormalizedText(payload.text, null),
+    contextText ? null : resolveNormalizedText(payload.text, resolveNormalizedText(payload.body, null)),
   );
   const commandText = resolveNormalizedText(payload.commandText, incomingText);
   const fromAgentId = resolveNormalizedText(metadata.fromAgentId, null);
-  const remoteIdentity = fromAgentId || 'unknown-peer';
+  const routeSessionKind = resolveNormalizedText(
+    event?.route?.sessionKind,
+    resolveNormalizedText(delivery.sessionKind, resolveNormalizedText(payload.sessionKind, null)),
+  );
+  const isRelayDelivery = eventType === 'delivery';
+  const allowReply = metadata.allowReply === true || (isRelayDelivery && metadata.allowReply !== false);
+  const remoteIdentity = fromAgentId
+    || resolveNormalizedText(metadata.source, routeSessionKind === 'management' ? 'claworld-management' : 'unknown-peer');
 
   if (
     !runtime?.channel?.reply?.finalizeInboundContext
     || !runtime?.channel?.reply?.dispatchReplyFromConfig
     || !runtime?.channel?.reply?.createReplyDispatcherWithTyping
   ) {
-    logger.warn?.(`[claworld:${runtimeAccountId}] skipping delivery bridge: missing runtime bridge hooks`, {
+    logger.warn?.(`[claworld:${runtimeAccountId}] skipping inbound bridge: missing runtime bridge hooks`, {
+      eventType,
       deliveryId,
       sessionKey,
     });
     return { skipped: true, reason: 'missing_runtime_bridge_hooks' };
   }
   if (!deliveryId || !sessionKey || (!incomingText && !contextText)) {
-    logger.warn?.(`[claworld:${runtimeAccountId}] skipping delivery bridge: missing delivery payload`, {
+    logger.warn?.(`[claworld:${runtimeAccountId}] skipping inbound bridge: missing payload`, {
+      eventType,
       deliveryId,
       sessionKey,
       hasIncomingText: Boolean(incomingText),
       hasContextText: Boolean(contextText),
     });
-    return { skipped: true, reason: 'missing_delivery_payload' };
+    return { skipped: true, reason: 'missing_inbound_payload' };
   }
 
   const loadedCfg = await runtime.config?.loadConfig?.() || {};
@@ -2247,7 +2291,7 @@ async function maybeBridgeRuntimeDelivery({
     fallbackTarget: runtimeConfig.routing?.fallbackTarget,
   }) || null;
   const worldId = resolveDeliveryWorldId(delivery);
-  const commandAuthorized = shouldAuthorizeBridgedCommand({
+  const commandAuthorized = isRelayDelivery && shouldAuthorizeBridgedCommand({
     runtimeConfig,
     incomingText: commandText || incomingText,
   });
@@ -2261,6 +2305,7 @@ async function maybeBridgeRuntimeDelivery({
     commandText,
     timestamp: inboundTimestamp,
     deliveryId,
+    eventType,
     sessionKey,
     localSessionKey,
     worldId,
@@ -2268,6 +2313,9 @@ async function maybeBridgeRuntimeDelivery({
     untrustedContext: payload.untrustedContext,
   });
   const localIdentity = normalizeClaworldText(runtimeConfig.relay?.agentId, runtimeConfig.accountId);
+  const isManagementSession = routeSessionKind === 'management';
+  const senderName = isManagementSession ? 'Claworld' : remoteIdentity;
+  const conversationLabel = isManagementSession ? 'Claworld management' : remoteIdentity;
   const inboundCtx = runtime.channel.reply.finalizeInboundContext({
     Body,
     RawBody,
@@ -2282,18 +2330,18 @@ async function maybeBridgeRuntimeDelivery({
     OriginatingChannel: 'claworld',
     OriginatingFrom: remoteIdentity,
     OriginatingTo: remoteIdentity,
-    ChatType: 'direct',
-    SenderName: remoteIdentity,
+    ChatType: isManagementSession ? 'management' : 'direct',
+    SenderName: senderName,
     SenderId: remoteIdentity,
     MessageId: deliveryId,
     Provider: 'claworld',
     Surface: 'claworld',
-    ConversationLabel: remoteIdentity,
+    ConversationLabel: conversationLabel,
     Timestamp: inboundTimestamp,
     MessageSid: deliveryId,
     WasMentioned: false,
     CommandAuthorized: commandAuthorized,
-    RelayDeliveryId: deliveryId,
+    RelayDeliveryId: isRelayDelivery ? deliveryId : null,
     RelayFromAgentId: fromAgentId,
     UntrustedContext,
   });
@@ -2308,6 +2356,7 @@ async function maybeBridgeRuntimeDelivery({
       ctx: inboundCtx,
       onRecordError: (error) => {
         logger.error?.(`[claworld:${runtimeAccountId}] failed to record inbound session`, {
+          eventType,
           deliveryId,
           sessionKey,
           localSessionKey,
@@ -2318,7 +2367,8 @@ async function maybeBridgeRuntimeDelivery({
     });
   }
 
-  logger.info?.(`[claworld:${runtimeAccountId}] routing delivery into runtime session`, {
+  logger.info?.(`[claworld:${runtimeAccountId}] ${isRelayDelivery ? 'routing delivery into runtime session' : 'routing inbound event into runtime session'}`, {
+    eventType,
     deliveryId,
     sessionKey,
     localSessionKey,
@@ -2327,27 +2377,29 @@ async function maybeBridgeRuntimeDelivery({
     routeStatus: routed?.status || null,
     bodyPreview: String(Body || '').slice(0, 240),
     rawBodyPreview: String(RawBody || '').slice(0, 240),
-    allowReply: metadata.allowReply !== false,
+    allowReply,
     commandAuthorized,
   });
 
-  try {
-    const acceptedResult = await relayClient.acceptDeliveryHttp({
-      deliveryId,
-      sessionKey,
-      source: 'runtime_dispatch',
-    });
-    if (acceptedResult.status < 200 || acceptedResult.status >= 300) {
-      throw new Error(`failed to submit relay delivery acceptance: ${acceptedResult.status}`);
+  if (isRelayDelivery && metadata.acceptanceRequired !== false) {
+    try {
+      const acceptedResult = await relayClient.acceptDeliveryHttp({
+        deliveryId,
+        sessionKey,
+        source: 'runtime_dispatch',
+      });
+      if (acceptedResult.status < 200 || acceptedResult.status >= 300) {
+        throw new Error(`failed to submit relay delivery acceptance: ${acceptedResult.status}`);
+      }
+    } catch (error) {
+      logger.warn?.(`[claworld:${runtimeAccountId}] delivery acceptance acknowledgement failed`, {
+        deliveryId,
+        sessionKey,
+        localSessionKey,
+        localAgentId,
+        error: error?.message || String(error),
+      });
     }
-  } catch (error) {
-    logger.warn?.(`[claworld:${runtimeAccountId}] delivery acceptance acknowledgement failed`, {
-      deliveryId,
-      sessionKey,
-      localSessionKey,
-      localAgentId,
-      error: error?.message || String(error),
-    });
   }
 
   let {
@@ -2362,15 +2414,16 @@ async function maybeBridgeRuntimeDelivery({
     deliveryId,
     sessionKey,
     localAgentId,
-    allowReply: metadata.allowReply !== false,
+    allowReply,
     logger,
     runtimeAccountId,
     inboundCtx,
   });
 
   const shouldRetryKickoffDispatch = (
-    metadata.deliveryType === 'kickoff'
-    && metadata.allowReply !== false
+    isRelayDelivery
+    && metadata.deliveryType === 'kickoff'
+    && allowReply
     && replied !== true
     && runtimeOutputSummary.counts.final > 0
     && runtimeOutputSummary.counts.nonRenderableFinal > 0
@@ -2407,14 +2460,15 @@ async function maybeBridgeRuntimeDelivery({
       deliveryId,
       sessionKey,
       localAgentId,
-      allowReply: metadata.allowReply !== false,
+      allowReply,
       logger,
       runtimeAccountId,
       inboundCtx,
     }));
   }
 
-  logger.info?.(`[claworld:${runtimeAccountId}] delivery bridge completed`, {
+  logger.info?.(`[claworld:${runtimeAccountId}] ${isRelayDelivery ? 'delivery bridge completed' : 'inbound bridge completed'}`, {
+    eventType,
     deliveryId,
     sessionKey,
     localSessionKey,
@@ -2874,9 +2928,9 @@ export function createClaworldChannelPlugin({
             sessionKey: event?.delivery?.sessionKey || null,
           });
 
-          if (event?.eventType === 'delivery') {
+          if (event?.delivery?.sessionKey) {
             const runtimeContext = accountRuntimeContexts.get(accountKey) || {};
-            maybeBridgeRuntimeDelivery({
+            maybeBridgeRuntimeInboundEvent({
               relayClient,
               runtimeConfig,
               runtimeAccountId,
@@ -2886,7 +2940,7 @@ export function createClaworldChannelPlugin({
               cfg: runtimeContext.cfg,
               inbound,
             }).catch((error) => {
-              logger.error?.(`[claworld:${runtimeAccountId}] delivery bridge exception`, {
+              logger.error?.(`[claworld:${runtimeAccountId}] inbound bridge exception`, {
                 error: error?.message || String(error),
               });
             });

package/src/openclaw/plugin/register.js

@@ -142,33 +142,6 @@ 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',
@@ -319,117 +292,6 @@ 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;
@@ -1062,27 +924,10 @@ 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,
-          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,
-          }),
+          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 }),
         },
       }),
       async execute(toolCallId, params = {}) {
@@ -1094,19 +939,10 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
           });
           return rewriteToolResultName(result, manageConversationsTool, action);
         }
-        if (action === 'list_related' || action === 'get_state') {
-          const filters = normalizeManageConversationInboxQuery(params, action);
+        if (['list_related', 'get_state', 'accept', 'reject'].includes(action)) {
           const result = await requireTerminalTool(internalTools, 'claworld_chat_inbox').execute(toolCallId, {
             ...params,
-            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,
+            action: ['list_related', 'get_state'].includes(action) ? 'list' : action,
           });
           return rewriteToolResultName(result, manageConversationsTool, action);
         }
@@ -1854,10 +1690,45 @@ function buildRegisteredTools(api, plugin) {
             examples: ['list', 'accept', 'reject'],
           }),
           filters: objectParam({
-            ...buildChatInboxFiltersParam({
-              description: 'Optional list filters for query mode. Omit to review the full inbox across inbound and outbound items.',
-              worldIdProperty,
-            }),
+            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'],
+              }),
+            },
           }),
           chatRequestId: stringParam({
             description: 'Canonical chat request id returned by claworld_chat_inbox pendingRequests. Required for action=accept or action=reject.',

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

@@ -5,6 +5,51 @@ export const STALE_CONNECTION_CLOSE_CODE = 4002;
 export const TERMINAL_CLOSE_REASONS = new Set(['duplicate_connection_replaced', 'stale_connection']);
 export const DEFAULT_REPLY_ACK_TIMEOUT_MS = 5000;
 
+function cloneObject(value, fallback = {}) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return { ...fallback };
+  return { ...value };
+}
+
+function normalizeEnvelopeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function resolveEnvelopeMessageId(data = {}, payload = {}) {
+  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 metadata = data.metadata && typeof data.metadata === 'object' && !Array.isArray(data.metadata)
+    ? data.metadata
+    : payload.metadata && typeof payload.metadata === 'object' && !Array.isArray(payload.metadata)
+      ? payload.metadata
+      : {};
+  const candidates = [
+    data.deliveryId,
+    data.inboxItemId,
+    data.messageId,
+    data.eventId,
+    data.notificationId,
+    payload.deliveryId,
+    payload.inboxItemId,
+    payload.messageId,
+    payload.eventId,
+    payload.notificationId,
+    metadata.messageId,
+    metadata.eventId,
+    metadata.notificationId,
+    notification.notificationId,
+  ];
+  for (const candidate of candidates) {
+    const normalized = normalizeEnvelopeText(candidate, null);
+    if (normalized) return normalized;
+  }
+  return null;
+}
+
 export function normalizeRelayWebSocketUrl(serverUrl) {
   const parsed = new URL(serverUrl);
   if (parsed.protocol === 'http:') parsed.protocol = 'ws:';
@@ -23,20 +68,63 @@ export function normalizeRelayWebSocketUrl(serverUrl) {
 
 export function buildInboundEnvelope(message = {}) {
   const data = message.data || {};
-  if (message.event !== 'delivery') return null;
+  const directPayload = data.payload && typeof data.payload === 'object' && !Array.isArray(data.payload)
+    ? { ...data.payload }
+    : {};
   const metadata = data.metadata && typeof data.metadata === 'object' && !Array.isArray(data.metadata)
     ? { ...data.metadata }
-    : {};
+    : directPayload.metadata && typeof directPayload.metadata === 'object' && !Array.isArray(directPayload.metadata)
+      ? { ...directPayload.metadata }
+      : cloneObject(data.meta, {});
+  const payloadEventType = normalizeEnvelopeText(directPayload.eventType, null);
+  const dataEventType = normalizeEnvelopeText(data.eventType, null);
+  const eventType = dataEventType
+    || payloadEventType
+    || (message.event === 'delivery' ? 'delivery' : normalizeEnvelopeText(message.event, null));
+  const payload = Object.keys(directPayload).length > 0
+    ? { ...directPayload }
+    : cloneObject(data, {});
+  if (Object.keys(directPayload).length > 0) {
+    for (const key of [
+      'eventType',
+      'eventName',
+      'sessionKind',
+      'sessionKey',
+      'targetSessionKey',
+      'targetAgentId',
+      'text',
+      'body',
+      'notification',
+    ]) {
+      if (payload[key] == null && data[key] != null) payload[key] = data[key];
+    }
+  }
+  const targetAgentId = normalizeEnvelopeText(
+    data.targetAgentId,
+    normalizeEnvelopeText(payload.targetAgentId, null),
+  );
+  const sessionKey = normalizeEnvelopeText(
+    data.sessionKey,
+    normalizeEnvelopeText(
+      payload.sessionKey,
+      normalizeEnvelopeText(
+        data.targetSessionKey,
+        normalizeEnvelopeText(payload.targetSessionKey, null),
+      ),
+    ),
+  );
+  const isDeliveryEvent = message.event === 'delivery';
+  const isRoutableEvent = Boolean(eventType && sessionKey);
+  if (!isDeliveryEvent && !isRoutableEvent) return null;
   return {
-    eventType: data.eventType || 'delivery',
-    deliveryId: data.deliveryId || null,
-    sessionKey: data.sessionKey || null,
-    createdAt: data.createdAt || null,
+    eventType: eventType || 'delivery',
+    deliveryId: resolveEnvelopeMessageId(data, payload),
+    sessionKey,
+    targetAgentId,
+    createdAt: data.createdAt || data.availableAt || null,
     updatedAt: data.updatedAt || null,
     turnCreatedAt: data.turnCreatedAt || null,
-    payload: data.payload && typeof data.payload === 'object' && !Array.isArray(data.payload)
-      ? { ...data.payload }
-      : {},
+    payload,
     metadata,
   };
 }

package/src/openclaw/runtime/session-routing.js

@@ -47,6 +47,10 @@ export function buildConversationSessionKey(conversationKey = null, fallbackSess
 export function resolveRuntimeSessionTarget(event = {}, options = {}) {
   const payload = normalizePayload(event.payload);
   const eventType = normalizeText(event.eventType || event.type || payload.eventType, null);
+  const providedSessionKind = normalizeText(
+    event.sessionKind,
+    normalizeText(payload.sessionKind, normalizeText(options.sessionKind, null)),
+  );
   const targetAgentId = normalizeText(
     event.targetAgentId,
     normalizeText(payload.targetAgentId, normalizeText(options.targetAgentId, null)),
@@ -60,15 +64,15 @@ export function resolveRuntimeSessionTarget(event = {}, options = {}) {
     normalizeText(payload.sessionKey, normalizeText(options.sessionKey, null)),
   );
 
-  if (CLAWORLD_MANAGEMENT_EVENT_TYPES.includes(eventType)) {
+  if (providedSessionKind === CLAWORLD_SESSION_KINDS.management || CLAWORLD_MANAGEMENT_EVENT_TYPES.includes(eventType)) {
     const managementSessionKey = normalizeText(
       options.managementSessionKey,
-      buildManagementSessionKey(targetAgentId),
+      normalizeText(providedSessionKey, buildManagementSessionKey(targetAgentId)),
     );
     return {
       sessionKind: CLAWORLD_SESSION_KINDS.management,
       target: normalizeText(options.managementTarget, 'management_session'),
-      sessionKey: managementSessionKey || providedSessionKey,
+      sessionKey: providedSessionKey || managementSessionKey,
       managementSessionKey: managementSessionKey || null,
       conversationSessionKey: conversationKey ? buildConversationSessionKey(conversationKey) : null,
       targetAgentId,