@xfxstudio/claworld 0.2.6 → 0.2.7

package/src/openclaw/plugin/register.js

@@ -1,6 +1,6 @@
 import { createClaworldChannelPlugin } from './claworld-channel-plugin.js';
 import {
-  projectToolChatRequestListResponse,
+  projectToolChatInboxResponse,
   projectToolChatRequestMutationResponse,
   projectToolCreateWorldResponse,
   projectToolManagedWorldResponse,
@@ -19,6 +19,8 @@ import {
   normalizeRuntimeBoundaryError,
 } from '../../lib/runtime-errors.js';
 
+const INTERNAL_REQUESTER_SESSION_KEY_PARAM = '__claworldRequesterSessionKey';
+
 function normalizeText(value, fallback = null) {
   if (value == null) return fallback;
   const normalized = String(value).trim();
@@ -166,6 +168,7 @@ async function resolveToolContext(api, plugin, params = {}) {
       accountId,
       runtimeConfig,
       agentId: normalizeText(params.agentId, runtimeConfig.relay?.agentId || null),
+      requesterSessionKey: normalizeText(params[INTERNAL_REQUESTER_SESSION_KEY_PARAM], null),
     });
   }
 
@@ -175,6 +178,7 @@ async function resolveToolContext(api, plugin, params = {}) {
     accountId,
     runtimeConfig,
     agentId,
+    requesterSessionKey: normalizeText(params[INTERNAL_REQUESTER_SESSION_KEY_PARAM], null),
   };
 }
 
@@ -567,7 +571,7 @@ function buildRegisteredTools(api, plugin) {
             input: {
               accountId: 'claworld',
               worldId: 'ugc-weekend-debate-club',
-              worldContextText: '世界：Weekend Debate Club [ugc-weekend-debate-club]\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.\n结果要求：Leave one clear 1 to 10 rating.',
+              worldContextText: '世界：Weekend Debate Club [ugc-weekend-debate-club]\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.',
             },
             outcome: 'Returns the updated managed-world projection when the current agent is the owner.',
           },
@@ -582,7 +586,7 @@ function buildRegisteredTools(api, plugin) {
           worldContextText: stringParam({
             description: 'Replacement canonical world context text for the owned world.',
             minLength: 1,
-            examples: ['世界：Weekend Debate Club [ugc-weekend-debate-club]\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.\n结果要求：Leave one clear 1 to 10 rating.'],
+            examples: ['世界：Weekend Debate Club [ugc-weekend-debate-club]\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.'],
           }),
           displayName: stringParam({
             description: 'Optional new display name for the owned world.',
@@ -598,7 +602,7 @@ function buildRegisteredTools(api, plugin) {
           {
             accountId: 'claworld',
             worldId: 'ugc-weekend-debate-club',
-            worldContextText: '世界：Weekend Debate Club [ugc-weekend-debate-club]\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.\n结果要求：Leave one clear 1 to 10 rating.',
+            worldContextText: '世界：Weekend Debate Club [ugc-weekend-debate-club]\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.',
           },
         ],
       }),
@@ -626,7 +630,7 @@ function buildRegisteredTools(api, plugin) {
         category: 'chat_request',
         usageNotes: [
           'For world-scoped chat, use the targetAgentId returned by claworld_join_world.',
-          'After creation, use claworld_list_chat_requests or wait for the peer to accept.',
+          'After creation, use claworld_chat_inbox or wait for the peer to accept.',
           'Once accepted, the runtime owns the live conversation loop.',
         ],
         examples: [
@@ -680,33 +684,36 @@ function buildRegisteredTools(api, plugin) {
       },
     },
     {
-      name: 'claworld_list_chat_requests',
-      label: 'Claworld List Chat Requests',
-      description: 'Canonical review tool for pending chat requests after request_chat or before accept_chat_request.',
+      name: 'claworld_chat_inbox',
+      label: 'Claworld Chat Inbox',
+      description: 'Canonical chat inbox tool. Review pending requests plus current or recent Claworld chats and the local session references you can use to check progress.',
       metadata: buildToolMetadata({
         category: 'chat_request',
         usageNotes: [
-          'Use to review inbound requests waiting for acceptance.',
-          'Use direction=outbound when checking whether a previously-created request is still pending.',
+          'Use to review pending inbound requests waiting for acceptance.',
+          'Use to locate the relevant Claworld chat and the local sessionKey tied to it.',
+          'If the user asks about one chat, first locate it here, then use your local session-send tool to ask that local session for a progress update or short summary.',
+          'Prefer asking the local chat session for a concise update before inspecting raw local transcript details.',
+          'Use direction=outbound when focusing on chats you initiated.',
         ],
         examples: [
           {
-            title: 'Review inbound requests',
+            title: 'Review inbound chat state',
             input: {
               accountId: 'claworld',
               direction: 'inbound',
             },
-            outcome: 'Returns the current pending or accepted chat requests for the current account.',
+            outcome: 'Returns pending requests plus related chats for the current account.',
           },
         ],
       }),
       parameters: objectParam({
-        description: 'List direct or world-scoped chat requests for the current account.',
+        description: 'Review overall Claworld chat state for the current account before deciding whether to accept a request or query one local chat session for progress.',
         required: ['accountId'],
         properties: {
           accountId: accountIdProperty,
           direction: stringParam({
-            description: 'Filter to inbound requests you can review or outbound requests you previously created.',
+            description: 'Filter to inbound or outbound chat state from the current account perspective.',
             enumValues: ['inbound', 'outbound'],
             examples: ['inbound'],
           }),
@@ -720,11 +727,11 @@ function buildRegisteredTools(api, plugin) {
       }),
       async execute(_toolCallId, params = {}) {
         const context = await resolveToolContext(api, plugin, params);
-        const payload = await plugin.helpers.social.listChatRequests({
+        const payload = await plugin.helpers.social.listChatInbox({
           ...context,
           direction: params.direction || null,
         });
-        return buildToolResult(projectToolChatRequestListResponse(payload, { accountId: context.accountId }));
+        return buildToolResult(projectToolChatInboxResponse(payload, { accountId: context.accountId }));
       },
     },
     {
@@ -734,7 +741,7 @@ function buildRegisteredTools(api, plugin) {
       metadata: buildToolMetadata({
         category: 'chat_request',
         usageNotes: [
-          'Use the chatRequestId returned by claworld_list_chat_requests.',
+          'Use the chatRequestId returned by claworld_chat_inbox pendingRequests.',
           'After acceptance, do not try to send a separate raw message tool call; wait for runtime-owned live conversation.',
         ],
         examples: [
@@ -754,7 +761,7 @@ function buildRegisteredTools(api, plugin) {
         properties: {
           accountId: accountIdProperty,
           chatRequestId: stringParam({
-            description: 'Canonical chat request id returned by claworld_list_chat_requests.',
+            description: 'Canonical chat request id returned by claworld_chat_inbox pendingRequests.',
             minLength: 1,
             examples: ['req_demo_1'],
           }),
@@ -1007,6 +1014,19 @@ export function registerClaworldPluginFull(api, plugin) {
   if (!plugin) {
     throw new Error('registerClaworldPluginFull requires a plugin instance');
   }
+  if (typeof api.on === 'function') {
+    api.on('before_tool_call', async (event, ctx) => {
+      if (event?.toolName !== 'claworld_request_chat') return;
+      const requesterSessionKey = normalizeText(ctx?.sessionKey, null);
+      if (!requesterSessionKey) return;
+      return {
+        params: {
+          ...(event?.params && typeof event.params === 'object' && !Array.isArray(event.params) ? event.params : {}),
+          [INTERNAL_REQUESTER_SESSION_KEY_PARAM]: requesterSessionKey,
+        },
+      };
+    });
+  }
   if (typeof api.registerHttpRoute === 'function') {
     api.registerHttpRoute(buildClaworldStatusRoute(plugin));
   }

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

@@ -15,6 +15,7 @@ import {
 const DUPLICATE_CONNECTION_CLOSE_CODE = 4001;
 const STALE_CONNECTION_CLOSE_CODE = 4002;
 const TERMINAL_CLOSE_REASONS = new Set(['duplicate_connection_replaced', 'stale_connection']);
+const DEFAULT_REPLY_ACK_TIMEOUT_MS = 5000;
 
 function normalizeRelayWebSocketUrl(serverUrl) {
   const parsed = new URL(serverUrl);
@@ -49,6 +50,90 @@ function buildInboundEnvelope(message = {}) {
   };
 }
 
+function normalizeOptionalText(value) {
+  if (value == null) return null;
+  const normalized = String(value).trim();
+  return normalized || null;
+}
+
+function buildReplyAckTimeoutError({ deliveryId, timeoutMs, context = {} } = {}) {
+  return createRuntimeBoundaryError({
+    code: 'relay_reply_ack_timeout',
+    category: 'transport',
+    status: 504,
+    message: `timed out waiting for relay reply acknowledgement for ${deliveryId || 'unknown-delivery'} after ${timeoutMs}ms`,
+    publicMessage: 'relay reply acknowledgement timed out',
+    recoverable: true,
+    context,
+  });
+}
+
+function buildReplyFallbackError({
+  deliveryId,
+  status,
+  body,
+  context = {},
+} = {}) {
+  return createRuntimeBoundaryError({
+    code: normalizeOptionalText(body?.code) || normalizeOptionalText(body?.error) || 'relay_reply_fallback_failed',
+    category: status >= 500 ? 'runtime' : 'transport',
+    status: Number.isInteger(status) ? status : 502,
+    message: normalizeOptionalText(body?.message) || normalizeOptionalText(body?.reason) || 'relay reply fallback failed',
+    publicMessage: 'relay reply fallback failed',
+    recoverable: status >= 500,
+    context: {
+      deliveryId: normalizeOptionalText(deliveryId),
+      ...context,
+    },
+  });
+}
+
+function buildKeepSilentAckTimeoutError({ deliveryId, timeoutMs, context = {} } = {}) {
+  return createRuntimeBoundaryError({
+    code: 'relay_kept_silent_ack_timeout',
+    category: 'transport',
+    status: 504,
+    message: `timed out waiting for relay kept_silent acknowledgement for ${deliveryId || 'unknown-delivery'} after ${timeoutMs}ms`,
+    publicMessage: 'relay kept_silent acknowledgement timed out',
+    recoverable: true,
+    context,
+  });
+}
+
+function buildKeepSilentFallbackError({
+  deliveryId,
+  status,
+  body,
+  context = {},
+} = {}) {
+  return createRuntimeBoundaryError({
+    code: normalizeOptionalText(body?.code) || normalizeOptionalText(body?.error) || 'relay_kept_silent_fallback_failed',
+    category: status >= 500 ? 'runtime' : 'transport',
+    status: Number.isInteger(status) ? status : 502,
+    message: normalizeOptionalText(body?.message) || normalizeOptionalText(body?.reason) || 'relay kept_silent fallback failed',
+    publicMessage: 'relay kept_silent fallback failed',
+    recoverable: status >= 500,
+    context: {
+      deliveryId: normalizeOptionalText(deliveryId),
+      ...context,
+    },
+  });
+}
+
+function isReplyAlreadyApplied(result = null, deliveryId = null) {
+  if (!result || result.status !== 409) return false;
+  if (normalizeOptionalText(result.body?.reason) !== 'delivery_not_replyable') return false;
+  if (normalizeOptionalText(result.body?.delivery?.deliveryId) !== normalizeOptionalText(deliveryId)) return false;
+  return normalizeOptionalText(result.body?.delivery?.status) === 'replied';
+}
+
+function isDeliveryKeptSilentAlreadyApplied(result = null, deliveryId = null) {
+  if (!result || result.status !== 409) return false;
+  if (normalizeOptionalText(result.body?.reason) !== 'delivery_not_replyable') return false;
+  if (normalizeOptionalText(result.body?.delivery?.deliveryId) !== normalizeOptionalText(deliveryId)) return false;
+  return normalizeOptionalText(result.body?.delivery?.status) === 'kept_silent';
+}
+
 export class ClaworldRelayClient extends EventEmitter {
   constructor({
     logger = console,
@@ -479,7 +564,7 @@ export class ClaworldRelayClient extends EventEmitter {
     config,
     agentId,
     credential = null,
-    clientVersion = 'claworld-plugin/0.1.5',
+    clientVersion = 'claworld-plugin/0.2.7',
     sessionTarget,
     fallbackTarget,
   } = {}) {
@@ -597,6 +682,419 @@ export class ClaworldRelayClient extends EventEmitter {
     });
   }
 
+  sendKeepSilent({ deliveryId, sessionKey, reason = null, source = 'openclaw-autochain' } = {}) {
+    const normalizedDeliveryId = normalizeOptionalText(deliveryId);
+    if (!normalizedDeliveryId) {
+      throw createRuntimeBoundaryError({
+        code: 'relay_delivery_id_required',
+        category: 'input',
+        status: 400,
+        message: 'deliveryId is required to mark relay delivery kept_silent',
+        publicMessage: 'deliveryId is required',
+        recoverable: true,
+      });
+    }
+    const envelope = {
+      deliveryId: normalizedDeliveryId,
+      sessionKey: normalizeOptionalText(sessionKey) || null,
+      reason: normalizeOptionalText(reason) || 'no_renderable_reply',
+      source: normalizeOptionalText(source) || 'openclaw-autochain',
+    };
+    this.send({
+      type: 'kept_silent',
+      deliveryId: envelope.deliveryId,
+      sessionKey: envelope.sessionKey,
+      payload: {
+        reason: envelope.reason,
+        source: envelope.source,
+      },
+    });
+    return envelope;
+  }
+
+  waitForReplyAck({ deliveryId, timeoutMs = DEFAULT_REPLY_ACK_TIMEOUT_MS } = {}) {
+    const normalizedDeliveryId = normalizeOptionalText(deliveryId);
+    if (!normalizedDeliveryId) {
+      return Promise.reject(createRuntimeBoundaryError({
+        code: 'relay_delivery_id_required',
+        category: 'input',
+        status: 400,
+        message: 'deliveryId is required to wait for relay reply acknowledgement',
+        publicMessage: 'deliveryId is required',
+        recoverable: true,
+      }));
+    }
+
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let timeout = null;
+
+      const cleanup = () => {
+        if (timeout) clearTimeout(timeout);
+        this.off('reply.accepted', onReplyAccepted);
+        this.off('disconnect', onDisconnect);
+        this.off('close', onDisconnect);
+      };
+
+      const settleResolve = (value) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve(value);
+      };
+
+      const settleReject = (error) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(error);
+      };
+
+      const onReplyAccepted = (message = {}) => {
+        const repliedDeliveryId = normalizeOptionalText(message?.data?.repliedDeliveryId);
+        if (repliedDeliveryId !== normalizedDeliveryId) return;
+        settleResolve(message);
+      };
+
+      const onDisconnect = (info = {}) => {
+        settleReject(createRuntimeBoundaryError({
+          code: 'relay_reply_ack_disconnected',
+          category: 'transport',
+          status: 502,
+          message: `relay websocket closed before reply acknowledgement for ${normalizedDeliveryId}`,
+          publicMessage: 'relay websocket closed before reply acknowledgement',
+          recoverable: true,
+          context: this.buildBoundaryContext({
+            stage: 'reply_ack_wait',
+            deliveryId: normalizedDeliveryId,
+            closeCode: info?.code ?? null,
+            closeReason: info?.reason || null,
+          }),
+        }));
+      };
+
+      this.on('reply.accepted', onReplyAccepted);
+      this.on('disconnect', onDisconnect);
+      this.on('close', onDisconnect);
+
+      timeout = setTimeout(() => {
+        settleReject(buildReplyAckTimeoutError({
+          deliveryId: normalizedDeliveryId,
+          timeoutMs,
+          context: this.buildBoundaryContext({
+            stage: 'reply_ack_wait',
+            deliveryId: normalizedDeliveryId,
+          }),
+        }));
+      }, timeoutMs);
+      if (typeof timeout.unref === 'function') timeout.unref();
+    });
+  }
+
+  waitForKeepSilentAck({ deliveryId, timeoutMs = DEFAULT_REPLY_ACK_TIMEOUT_MS } = {}) {
+    const normalizedDeliveryId = normalizeOptionalText(deliveryId);
+    if (!normalizedDeliveryId) {
+      return Promise.reject(createRuntimeBoundaryError({
+        code: 'relay_delivery_id_required',
+        category: 'input',
+        status: 400,
+        message: 'deliveryId is required to wait for relay kept_silent acknowledgement',
+        publicMessage: 'deliveryId is required',
+        recoverable: true,
+      }));
+    }
+
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let timeout = null;
+
+      const cleanup = () => {
+        if (timeout) clearTimeout(timeout);
+        this.off('kept_silent.accepted', onKeptSilentAccepted);
+        this.off('disconnect', onDisconnect);
+        this.off('close', onDisconnect);
+      };
+
+      const settleResolve = (value) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve(value);
+      };
+
+      const settleReject = (error) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(error);
+      };
+
+      const onKeptSilentAccepted = (message = {}) => {
+        const keptSilentDeliveryId = normalizeOptionalText(message?.data?.keptSilentDeliveryId);
+        if (keptSilentDeliveryId !== normalizedDeliveryId) return;
+        settleResolve(message);
+      };
+
+      const onDisconnect = (info = {}) => {
+        settleReject(createRuntimeBoundaryError({
+          code: 'relay_kept_silent_ack_disconnected',
+          category: 'transport',
+          status: 502,
+          message: `relay websocket closed before kept_silent acknowledgement for ${normalizedDeliveryId}`,
+          publicMessage: 'relay websocket closed before kept_silent acknowledgement',
+          recoverable: true,
+          context: this.buildBoundaryContext({
+            stage: 'kept_silent_ack_wait',
+            deliveryId: normalizedDeliveryId,
+            closeCode: info?.code ?? null,
+            closeReason: info?.reason || null,
+          }),
+        }));
+      };
+
+      this.on('kept_silent.accepted', onKeptSilentAccepted);
+      this.on('disconnect', onDisconnect);
+      this.on('close', onDisconnect);
+
+      timeout = setTimeout(() => {
+        settleReject(buildKeepSilentAckTimeoutError({
+          deliveryId: normalizedDeliveryId,
+          timeoutMs,
+          context: this.buildBoundaryContext({
+            stage: 'kept_silent_ack_wait',
+            deliveryId: normalizedDeliveryId,
+          }),
+        }));
+      }, timeoutMs);
+      if (typeof timeout.unref === 'function') timeout.unref();
+    });
+  }
+
+  async replyToDeliveryHttp({ deliveryId, replyText, source = 'subagent' } = {}) {
+    const envelope = this.outbound.createReplyEnvelope({
+      deliveryId,
+      sessionKey: null,
+      replyText,
+      source,
+    });
+    const result = await this.requestJson(`/v1/deliveries/${encodeURIComponent(envelope.deliveryId)}/reply`, {
+      method: 'POST',
+      headers: buildRuntimeAuthHeaders(this.runtimeConfig, { 'content-type': 'application/json' }),
+      body: JSON.stringify({
+        fromAgentId: this.boundAgentId,
+        payload: {
+          ...envelope.payload,
+        },
+      }),
+    }, {
+      code: 'relay_reply_fallback_failed',
+      message: 'failed to submit relay reply fallback',
+      publicMessage: 'failed to submit relay reply fallback',
+    });
+    return {
+      ...result,
+      envelope,
+    };
+  }
+
+  async sendReplyAndWaitForAck({
+    deliveryId,
+    sessionKey,
+    replyText,
+    source = 'subagent',
+    timeoutMs = DEFAULT_REPLY_ACK_TIMEOUT_MS,
+    httpFallback = true,
+  } = {}) {
+    const envelope = this.sendReply({
+      deliveryId,
+      sessionKey,
+      replyText,
+      source,
+    });
+
+    try {
+      const ack = await this.waitForReplyAck({
+        deliveryId: envelope.deliveryId,
+        timeoutMs,
+      });
+      return {
+        ok: true,
+        envelope,
+        ack,
+        transport: 'websocket',
+        fallbackUsed: false,
+      };
+    } 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,
+        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,
+        }),
+      });
+    }
+  }
+
+  async keepDeliverySilentHttp({ deliveryId, reason = null, source = 'openclaw-autochain' } = {}) {
+    const normalizedDeliveryId = normalizeOptionalText(deliveryId);
+    const result = await this.requestJson(`/v1/deliveries/${encodeURIComponent(normalizedDeliveryId)}/kept-silent`, {
+      method: 'POST',
+      headers: buildRuntimeAuthHeaders(this.runtimeConfig, { 'content-type': 'application/json' }),
+      body: JSON.stringify({
+        fromAgentId: this.boundAgentId,
+        reason: normalizeOptionalText(reason) || 'no_renderable_reply',
+        source: normalizeOptionalText(source) || 'openclaw-autochain',
+      }),
+    }, {
+      code: 'relay_kept_silent_fallback_failed',
+      message: 'failed to submit relay kept_silent fallback',
+      publicMessage: 'failed to submit relay kept_silent fallback',
+    });
+    return {
+      ...result,
+      envelope: {
+        deliveryId: normalizedDeliveryId,
+        reason: normalizeOptionalText(reason) || 'no_renderable_reply',
+        source: normalizeOptionalText(source) || 'openclaw-autochain',
+      },
+    };
+  }
+
+  async sendKeepSilentAndWaitForAck({
+    deliveryId,
+    sessionKey,
+    reason = null,
+    source = 'openclaw-autochain',
+    timeoutMs = DEFAULT_REPLY_ACK_TIMEOUT_MS,
+    httpFallback = true,
+  } = {}) {
+    const envelope = this.sendKeepSilent({
+      deliveryId,
+      sessionKey,
+      reason,
+      source,
+    });
+
+    try {
+      const ack = await this.waitForKeepSilentAck({
+        deliveryId: envelope.deliveryId,
+        timeoutMs,
+      });
+      return {
+        ok: true,
+        envelope,
+        ack,
+        transport: 'websocket',
+        fallbackUsed: false,
+      };
+    } 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,
+        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,
+        }),
+      });
+    }
+  }
+
   async createChatRequest({ fromAgentId, toAddress, requestContext = {} } = {}) {
     const target = await this.requestJson(`/v1/agents/resolve?address=${encodeURIComponent(toAddress)}`, {
       method: 'GET',
@@ -618,6 +1116,9 @@ export class ClaworldRelayClient extends EventEmitter {
         kickoffBrief: normalized.kickoffBrief || null,
         openingMessage: normalized.openingMessage || null,
         worldId: normalized.conversation?.worldId || null,
+        requestContext: requestContext && typeof requestContext === 'object' && !Array.isArray(requestContext)
+          ? requestContext
+          : undefined,
       }),
     }, {
       code: 'relay_request_create_failed',