@xfxstudio/claworld 2026.4.30-testing.1 → 2026.4.30-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.30-testing.1",
+  "version": "2026.4.30-testing.3",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

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

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/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/plugin/relay-client.js

@@ -557,19 +557,23 @@ export class ClaworldRelayClient extends EventEmitter {
     this.heartbeatTimer = null;
   }
 
+  buildWsNotConnectedError(stage = 'send') {
+    return createRuntimeBoundaryError({
+      code: 'relay_ws_not_connected',
+      category: 'transport',
+      status: 409,
+      message: 'relay websocket is not connected',
+      publicMessage: 'relay websocket is not connected',
+      recoverable: true,
+      context: this.buildBoundaryContext({
+        stage,
+      }),
+    });
+  }
+
   send(payload) {
     if (!this.ws || this.ws.readyState !== 1) {
-      throw createRuntimeBoundaryError({
-        code: 'relay_ws_not_connected',
-        category: 'transport',
-        status: 409,
-        message: 'relay websocket is not connected',
-        publicMessage: 'relay websocket is not connected',
-        recoverable: true,
-        context: this.buildBoundaryContext({
-          stage: 'send',
-        }),
-      });
+      throw this.buildWsNotConnectedError('send');
     }
     this.ws.send(JSON.stringify(payload));
   }
@@ -663,7 +667,7 @@ export class ClaworldRelayClient extends EventEmitter {
     return envelope;
   }
 
-  waitForReplyAck({ deliveryId, timeoutMs = DEFAULT_REPLY_ACK_TIMEOUT_MS } = {}) {
+  waitForReplyAck({ deliveryId, timeoutMs = DEFAULT_REPLY_ACK_TIMEOUT_MS, signal = null } = {}) {
     const normalizedDeliveryId = normalizeOptionalText(deliveryId);
     if (!normalizedDeliveryId) {
       return Promise.reject(createRuntimeBoundaryError({
@@ -675,6 +679,20 @@ export class ClaworldRelayClient extends EventEmitter {
         recoverable: true,
       }));
     }
+    if (signal?.aborted) {
+      return Promise.reject(createRuntimeBoundaryError({
+        code: 'relay_reply_ack_wait_cancelled',
+        category: 'transport',
+        status: 499,
+        message: `relay reply acknowledgement wait cancelled for ${normalizedDeliveryId}`,
+        publicMessage: 'relay reply acknowledgement wait cancelled',
+        recoverable: true,
+        context: this.buildBoundaryContext({
+          stage: 'reply_ack_wait',
+          deliveryId: normalizedDeliveryId,
+        }),
+      }));
+    }
 
     return new Promise((resolve, reject) => {
       let settled = false;
@@ -686,6 +704,7 @@ export class ClaworldRelayClient extends EventEmitter {
         this.off('command.accepted', onCommandAccepted);
         this.off('disconnect', onDisconnect);
         this.off('close', onDisconnect);
+        signal?.removeEventListener('abort', onAbort);
       };
 
       const settleResolve = (value) => {
@@ -739,10 +758,26 @@ export class ClaworldRelayClient extends EventEmitter {
         }));
       };
 
+      const onAbort = () => {
+        settleReject(createRuntimeBoundaryError({
+          code: 'relay_reply_ack_wait_cancelled',
+          category: 'transport',
+          status: 499,
+          message: `relay reply acknowledgement wait cancelled for ${normalizedDeliveryId}`,
+          publicMessage: 'relay reply acknowledgement wait cancelled',
+          recoverable: true,
+          context: this.buildBoundaryContext({
+            stage: 'reply_ack_wait',
+            deliveryId: normalizedDeliveryId,
+          }),
+        }));
+      };
+
       this.on('reply.accepted', onReplyAccepted);
       this.on('command.accepted', onCommandAccepted);
       this.on('disconnect', onDisconnect);
       this.on('close', onDisconnect);
+      signal?.addEventListener('abort', onAbort, { once: true });
 
       timeout = setTimeout(() => {
         settleReject(buildReplyAckTimeoutError({
@@ -837,7 +872,7 @@ export class ClaworldRelayClient extends EventEmitter {
     });
   }
 
-  waitForKeepSilentAck({ deliveryId, timeoutMs = DEFAULT_REPLY_ACK_TIMEOUT_MS } = {}) {
+  waitForKeepSilentAck({ deliveryId, timeoutMs = DEFAULT_REPLY_ACK_TIMEOUT_MS, signal = null } = {}) {
     const normalizedDeliveryId = normalizeOptionalText(deliveryId);
     if (!normalizedDeliveryId) {
       return Promise.reject(createRuntimeBoundaryError({
@@ -849,6 +884,20 @@ export class ClaworldRelayClient extends EventEmitter {
         recoverable: true,
       }));
     }
+    if (signal?.aborted) {
+      return Promise.reject(createRuntimeBoundaryError({
+        code: 'relay_kept_silent_ack_wait_cancelled',
+        category: 'transport',
+        status: 499,
+        message: `relay kept_silent acknowledgement wait cancelled for ${normalizedDeliveryId}`,
+        publicMessage: 'relay kept_silent acknowledgement wait cancelled',
+        recoverable: true,
+        context: this.buildBoundaryContext({
+          stage: 'kept_silent_ack_wait',
+          deliveryId: normalizedDeliveryId,
+        }),
+      }));
+    }
 
     return new Promise((resolve, reject) => {
       let settled = false;
@@ -859,6 +908,7 @@ export class ClaworldRelayClient extends EventEmitter {
         this.off('kept_silent.accepted', onKeptSilentAccepted);
         this.off('disconnect', onDisconnect);
         this.off('close', onDisconnect);
+        signal?.removeEventListener('abort', onAbort);
       };
 
       const settleResolve = (value) => {
@@ -898,9 +948,25 @@ export class ClaworldRelayClient extends EventEmitter {
         }));
       };
 
+      const onAbort = () => {
+        settleReject(createRuntimeBoundaryError({
+          code: 'relay_kept_silent_ack_wait_cancelled',
+          category: 'transport',
+          status: 499,
+          message: `relay kept_silent acknowledgement wait cancelled for ${normalizedDeliveryId}`,
+          publicMessage: 'relay kept_silent acknowledgement wait cancelled',
+          recoverable: true,
+          context: this.buildBoundaryContext({
+            stage: 'kept_silent_ack_wait',
+            deliveryId: normalizedDeliveryId,
+          }),
+        }));
+      };
+
       this.on('kept_silent.accepted', onKeptSilentAccepted);
       this.on('disconnect', onDisconnect);
       this.on('close', onDisconnect);
+      signal?.addEventListener('abort', onAbort, { once: true });
 
       timeout = setTimeout(() => {
         settleReject(buildKeepSilentAckTimeoutError({
@@ -943,6 +1009,69 @@ export class ClaworldRelayClient extends EventEmitter {
     };
   }
 
+  async submitReplyHttpFallback({
+    deliveryId,
+    sessionKey,
+    replyText,
+    source = 'subagent',
+    error = null,
+  } = {}) {
+    this.logger.warn?.('[claworld:relay-client] reply websocket transport failed; attempting HTTP fallback', {
+      accountId: this.runtimeConfig?.accountId || null,
+      agentId: this.boundAgentId,
+      deliveryId: normalizeOptionalText(deliveryId),
+      sessionKey: normalizeOptionalText(sessionKey) || null,
+      error: error?.message || String(error),
+    });
+
+    const fallbackResult = await this.replyToDeliveryHttp({
+      deliveryId,
+      replyText,
+      source,
+    });
+
+    if (fallbackResult.status >= 200 && fallbackResult.status < 300) {
+      return {
+        ok: true,
+        envelope: fallbackResult.envelope,
+        ack: {
+          event: 'reply.accepted',
+          data: fallbackResult.body,
+        },
+        transport: 'http',
+        fallbackUsed: true,
+      };
+    }
+
+    if (isReplyAlreadyApplied(fallbackResult, fallbackResult.envelope.deliveryId)) {
+      return {
+        ok: true,
+        envelope: fallbackResult.envelope,
+        ack: {
+          event: 'reply.accepted',
+          data: {
+            ...(fallbackResult.body && typeof fallbackResult.body === 'object' ? fallbackResult.body : {}),
+            repliedDeliveryId: fallbackResult.envelope.deliveryId,
+          },
+        },
+        transport: 'http-already-applied',
+        fallbackUsed: true,
+      };
+    }
+
+    throw buildReplyFallbackError({
+      deliveryId: fallbackResult.envelope.deliveryId,
+      status: fallbackResult.status,
+      body: fallbackResult.body,
+      context: this.buildBoundaryContext({
+        stage: 'reply_fallback',
+        deliveryId: fallbackResult.envelope.deliveryId,
+        sessionKey: normalizeOptionalText(sessionKey) || null,
+        fallbackFrom: error?.code || error?.message || null,
+      }),
+    });
+  }
+
   async acceptDeliveryHttp({ deliveryId, sessionKey = null, source = 'runtime_dispatch' } = {}) {
     const normalizedDeliveryId = normalizeOptionalText(deliveryId);
     const result = await this.requestJsonWithDeliveryVisibilityRetry(`/v1/runtime-deliveries/${encodeURIComponent(normalizedDeliveryId)}/accepted`, {
@@ -976,16 +1105,43 @@ export class ClaworldRelayClient extends EventEmitter {
     timeoutMs = DEFAULT_REPLY_ACK_TIMEOUT_MS,
     httpFallback = true,
   } = {}) {
+    if (httpFallback && (!this.ws || this.ws.readyState !== 1)) {
+      return await this.submitReplyHttpFallback({
+        deliveryId,
+        sessionKey,
+        replyText,
+        source,
+        error: this.buildWsNotConnectedError('reply_send'),
+      });
+    }
+
+    const ackAbortController = new AbortController();
     const ackPromise = this.waitForReplyAck({
       deliveryId,
       timeoutMs,
+      signal: ackAbortController.signal,
     });
-    const envelope = this.sendReply({
-      deliveryId,
-      sessionKey,
-      replyText,
-      source,
-    });
+    let envelope;
+
+    try {
+      envelope = this.sendReply({
+        deliveryId,
+        sessionKey,
+        replyText,
+        source,
+      });
+    } catch (error) {
+      ackAbortController.abort();
+      void ackPromise.catch(() => {});
+      if (!httpFallback) throw error;
+      return await this.submitReplyHttpFallback({
+        deliveryId,
+        sessionKey,
+        replyText,
+        source,
+        error,
+      });
+    }
 
     try {
       const ack = await ackPromise;
@@ -999,59 +1155,12 @@ export class ClaworldRelayClient extends EventEmitter {
     } catch (error) {
       if (!httpFallback) throw error;
 
-      this.logger.warn?.('[claworld:relay-client] reply websocket acknowledgement failed; attempting HTTP fallback', {
-        accountId: this.runtimeConfig?.accountId || null,
-        agentId: this.boundAgentId,
+      return await this.submitReplyHttpFallback({
         deliveryId: envelope.deliveryId,
         sessionKey: envelope.sessionKey,
-        error: error?.message || String(error),
-      });
-
-      const fallbackResult = await this.replyToDeliveryHttp({
-        deliveryId: envelope.deliveryId,
         replyText,
         source,
-      });
-
-      if (fallbackResult.status >= 200 && fallbackResult.status < 300) {
-        return {
-          ok: true,
-          envelope,
-          ack: {
-            event: 'reply.accepted',
-            data: fallbackResult.body,
-          },
-          transport: 'http',
-          fallbackUsed: true,
-        };
-      }
-
-      if (isReplyAlreadyApplied(fallbackResult, envelope.deliveryId)) {
-        return {
-          ok: true,
-          envelope,
-          ack: {
-            event: 'reply.accepted',
-            data: {
-              ...(fallbackResult.body && typeof fallbackResult.body === 'object' ? fallbackResult.body : {}),
-              repliedDeliveryId: envelope.deliveryId,
-            },
-          },
-          transport: 'http-already-applied',
-          fallbackUsed: true,
-        };
-      }
-
-      throw buildReplyFallbackError({
-        deliveryId: envelope.deliveryId,
-        status: fallbackResult.status,
-        body: fallbackResult.body,
-        context: this.buildBoundaryContext({
-          stage: 'reply_fallback',
-          deliveryId: envelope.deliveryId,
-          sessionKey: envelope.sessionKey,
-          fallbackFrom: error?.code || error?.message || null,
-        }),
+        error,
       });
     }
   }
@@ -1169,6 +1278,69 @@ export class ClaworldRelayClient extends EventEmitter {
     };
   }
 
+  async submitKeepSilentHttpFallback({
+    deliveryId,
+    sessionKey,
+    reason = null,
+    source = 'openclaw-autochain',
+    error = null,
+  } = {}) {
+    this.logger.warn?.('[claworld:relay-client] kept_silent websocket transport failed; attempting HTTP fallback', {
+      accountId: this.runtimeConfig?.accountId || null,
+      agentId: this.boundAgentId,
+      deliveryId: normalizeOptionalText(deliveryId),
+      sessionKey: normalizeOptionalText(sessionKey) || null,
+      error: error?.message || String(error),
+    });
+
+    const fallbackResult = await this.keepDeliverySilentHttp({
+      deliveryId,
+      reason,
+      source,
+    });
+
+    if (fallbackResult.status >= 200 && fallbackResult.status < 300) {
+      return {
+        ok: true,
+        envelope: fallbackResult.envelope,
+        ack: {
+          event: 'kept_silent.accepted',
+          data: fallbackResult.body,
+        },
+        transport: 'http',
+        fallbackUsed: true,
+      };
+    }
+
+    if (isDeliveryKeptSilentAlreadyApplied(fallbackResult, fallbackResult.envelope.deliveryId)) {
+      return {
+        ok: true,
+        envelope: fallbackResult.envelope,
+        ack: {
+          event: 'kept_silent.accepted',
+          data: {
+            ...(fallbackResult.body && typeof fallbackResult.body === 'object' ? fallbackResult.body : {}),
+            keptSilentDeliveryId: fallbackResult.envelope.deliveryId,
+          },
+        },
+        transport: 'http-already-applied',
+        fallbackUsed: true,
+      };
+    }
+
+    throw buildKeepSilentFallbackError({
+      deliveryId: fallbackResult.envelope.deliveryId,
+      status: fallbackResult.status,
+      body: fallbackResult.body,
+      context: this.buildBoundaryContext({
+        stage: 'kept_silent_fallback',
+        deliveryId: fallbackResult.envelope.deliveryId,
+        sessionKey: normalizeOptionalText(sessionKey) || null,
+        fallbackFrom: error?.code || error?.message || null,
+      }),
+    });
+  }
+
   async sendKeepSilentAndWaitForAck({
     deliveryId,
     sessionKey,
@@ -1177,16 +1349,43 @@ export class ClaworldRelayClient extends EventEmitter {
     timeoutMs = DEFAULT_REPLY_ACK_TIMEOUT_MS,
     httpFallback = true,
   } = {}) {
+    if (httpFallback && (!this.ws || this.ws.readyState !== 1)) {
+      return await this.submitKeepSilentHttpFallback({
+        deliveryId,
+        sessionKey,
+        reason,
+        source,
+        error: this.buildWsNotConnectedError('kept_silent_send'),
+      });
+    }
+
+    const ackAbortController = new AbortController();
     const ackPromise = this.waitForKeepSilentAck({
       deliveryId,
       timeoutMs,
+      signal: ackAbortController.signal,
     });
-    const envelope = this.sendKeepSilent({
-      deliveryId,
-      sessionKey,
-      reason,
-      source,
-    });
+    let envelope;
+
+    try {
+      envelope = this.sendKeepSilent({
+        deliveryId,
+        sessionKey,
+        reason,
+        source,
+      });
+    } catch (error) {
+      ackAbortController.abort();
+      void ackPromise.catch(() => {});
+      if (!httpFallback) throw error;
+      return await this.submitKeepSilentHttpFallback({
+        deliveryId,
+        sessionKey,
+        reason,
+        source,
+        error,
+      });
+    }
 
     try {
       const ack = await ackPromise;
@@ -1200,59 +1399,12 @@ export class ClaworldRelayClient extends EventEmitter {
     } catch (error) {
       if (!httpFallback) throw error;
 
-      this.logger.warn?.('[claworld:relay-client] kept_silent websocket acknowledgement failed; attempting HTTP fallback', {
-        accountId: this.runtimeConfig?.accountId || null,
-        agentId: this.boundAgentId,
+      return await this.submitKeepSilentHttpFallback({
         deliveryId: envelope.deliveryId,
         sessionKey: envelope.sessionKey,
-        error: error?.message || String(error),
-      });
-
-      const fallbackResult = await this.keepDeliverySilentHttp({
-        deliveryId: envelope.deliveryId,
         reason: envelope.reason,
         source: envelope.source,
-      });
-
-      if (fallbackResult.status >= 200 && fallbackResult.status < 300) {
-        return {
-          ok: true,
-          envelope,
-          ack: {
-            event: 'kept_silent.accepted',
-            data: fallbackResult.body,
-          },
-          transport: 'http',
-          fallbackUsed: true,
-        };
-      }
-
-      if (isDeliveryKeptSilentAlreadyApplied(fallbackResult, envelope.deliveryId)) {
-        return {
-          ok: true,
-          envelope,
-          ack: {
-            event: 'kept_silent.accepted',
-            data: {
-              ...(fallbackResult.body && typeof fallbackResult.body === 'object' ? fallbackResult.body : {}),
-              keptSilentDeliveryId: envelope.deliveryId,
-            },
-          },
-          transport: 'http-already-applied',
-          fallbackUsed: true,
-        };
-      }
-
-      throw buildKeepSilentFallbackError({
-        deliveryId: envelope.deliveryId,
-        status: fallbackResult.status,
-        body: fallbackResult.body,
-        context: this.buildBoundaryContext({
-          stage: 'kept_silent_fallback',
-          deliveryId: envelope.deliveryId,
-          sessionKey: envelope.sessionKey,
-          fallbackFrom: error?.code || error?.message || null,
-        }),
+        error,
       });
     }
   }

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,