@xfxstudio/claworld 0.2.23 → 0.2.25

package/src/openclaw/plugin/managed-config.js

@@ -13,6 +13,8 @@ export const DEFAULT_CLAWORLD_AGENT_ID = 'main';
 export const DEFAULT_CLAWORLD_ACCOUNT_ID = 'claworld';
 export const DEFAULT_CLAWORLD_TOOL_PROFILE = 'default';
 export const DEFAULT_CLAWORLD_DM_SCOPE = 'per-channel-peer';
+export const DEFAULT_CLAWORLD_SESSION_RESET_MODE = 'idle';
+export const DEFAULT_CLAWORLD_SESSION_RESET_IDLE_MINUTES = 43200;
 export const DEFAULT_CLAWORLD_SESSION_TARGET = 'mainagent';
 export const DEFAULT_CLAWORLD_FALLBACK_TARGET = 'mainagent';
 export const CLAWORLD_PLUGIN_TOOL_ALLOW_ENTRY = 'claworld';
@@ -44,6 +46,13 @@ export function ensureObject(value) {
   return value;
 }
 
+function buildDefaultClaworldSessionResetOverride() {
+  return {
+    mode: DEFAULT_CLAWORLD_SESSION_RESET_MODE,
+    idleMinutes: DEFAULT_CLAWORLD_SESSION_RESET_IDLE_MINUTES,
+  };
+}
+
 function normalizeRegistrationDisplayName(value, fallback = null) {
   const normalized = normalizeText(value, fallback);
   return normalized || fallback;
@@ -713,6 +722,16 @@ export function applyClaworldManagedRuntimeConfig(inputConfig = {}, options = {}
     config.session.dmScope = sessionDmScope;
     summary.push(`session.dmScope set to ${sessionDmScope}`);
   }
+  const resetByChannel = ensureObject(config.session.resetByChannel);
+  if (!Object.prototype.hasOwnProperty.call(resetByChannel, 'claworld')) {
+    config.session.resetByChannel = {
+      ...resetByChannel,
+      claworld: buildDefaultClaworldSessionResetOverride(),
+    };
+    summary.push(
+      `session.resetByChannel.claworld set to ${DEFAULT_CLAWORLD_SESSION_RESET_MODE}/${DEFAULT_CLAWORLD_SESSION_RESET_IDLE_MINUTES}m`,
+    );
+  }
 
   config.agents = ensureObject(config.agents);
   const existingAgentList = Array.isArray(config.agents.list) ? [...config.agents.list] : [];

package/src/openclaw/plugin/register-tooling.js

@@ -3,6 +3,8 @@ import {
   projectToolChatRequestMutationResponse,
   projectToolManagedWorldResponse,
   projectToolOwnedWorldsResponse,
+  projectToolWorldMembershipListResponse,
+  projectToolWorldMembershipResponse,
 } from '../runtime/tool-contracts.js';
 import {
   buildPublicErrorPayload,
@@ -383,6 +385,10 @@ export const MANAGE_WORLD_ACTIONS = Object.freeze([
   'pause',
   'close',
   'resume',
+  'list_memberships',
+  'get_membership',
+  'update_profile',
+  'leave',
 ]);
 
 export function normalizeManageWorldAction(value, fallback = null) {
@@ -394,6 +400,7 @@ export function inferManageWorldAction(params = {}) {
   const explicitAction = normalizeManageWorldAction(params.action, null);
   if (explicitAction) return explicitAction;
   if (!normalizeText(params.worldId, null)) return 'list';
+  if (normalizeText(params.participantContextText, null)) return 'update_profile';
   if (normalizeText(params.worldContextText, null) || normalizeText(params.displayName, null)) {
     return 'update_context';
   }
@@ -420,6 +427,18 @@ export function projectToolManageWorldActionResponse(payload = {}, { accountId =
       ...projectToolOwnedWorldsResponse(payload, { accountId }),
     };
   }
+  if (resolvedAction === 'list_memberships') {
+    return {
+      action: resolvedAction,
+      ...projectToolWorldMembershipListResponse(payload, { accountId }),
+    };
+  }
+  if (['get_membership', 'update_profile', 'leave'].includes(resolvedAction)) {
+    return {
+      action: resolvedAction,
+      ...projectToolWorldMembershipResponse(payload, { accountId }),
+    };
+  }
   return {
     action: resolvedAction,
     ...projectToolManagedWorldResponse(payload, { accountId }),
@@ -585,6 +604,31 @@ function projectToolChatRequestApprovalPolicy(payload = null) {
   };
 }
 
+function projectToolPluginVersionStatus(payload = null) {
+  const versionStatus = normalizeObject(payload, null);
+  if (!versionStatus) return null;
+
+  const warning = normalizeObject(versionStatus.warning, null);
+  return {
+    reportedVersion: normalizeText(versionStatus.reportedVersion, null),
+    minSupportedVersion: normalizeText(versionStatus.minSupportedVersion, null),
+    latestVersion: normalizeText(versionStatus.latestVersion, null),
+    compatible: typeof versionStatus.compatible === 'boolean' ? versionStatus.compatible : null,
+    status: normalizeText(versionStatus.status, 'unknown'),
+    upgradeCommand: normalizeText(versionStatus.upgradeCommand, null),
+    message: normalizeText(versionStatus.message, null),
+    ...(warning
+      ? {
+          warning: {
+            level: normalizeText(warning.level, null),
+            code: normalizeText(warning.code, null),
+            message: normalizeText(warning.message, null),
+          },
+        }
+      : {}),
+  };
+}
+
 export function projectToolAccountViewResponse({
   accountId = null,
   pairingPayload = null,
@@ -622,6 +666,7 @@ export function projectToolAccountViewResponse({
     },
     profile: projectToolAccountProfile(identityPayload),
     ...projectToolAccountIdentityFields(identityPayload),
+    pluginVersionStatus: projectToolPluginVersionStatus(identityPayload?.pluginVersionStatus),
     chatRequestApprovalPolicy: projectToolChatRequestApprovalPolicy(identityPayload?.chatRequestApprovalPolicy),
     ...(resolvedShareCard !== undefined ? { shareCard: resolvedShareCard } : {}),
   };
@@ -647,6 +692,7 @@ export function projectToolAccountMutationResponse({
     accountId: normalizeText(accountId, null),
     profile: projectToolAccountProfile(identityPayload),
     ...projectToolAccountIdentityFields(identityPayload),
+    pluginVersionStatus: projectToolPluginVersionStatus(identityPayload?.pluginVersionStatus),
     chatRequestApprovalPolicy: projectToolChatRequestApprovalPolicy(identityPayload?.chatRequestApprovalPolicy),
     ...(resolvedShareCard !== undefined ? { shareCard: resolvedShareCard } : {}),
     ...(runtimeActivation ? { runtimeActivation } : {}),

package/src/openclaw/plugin/register.js

@@ -324,13 +324,13 @@ function buildRegisteredTools(api, plugin) {
     {
       name: 'claworld_create_world',
       label: 'Claworld Create World',
-      description: 'Creator/admin entrypoint for publishing one new owner-managed world. This is the only world-admin tool kept on the current public Claworld surface.',
+      description: 'Creator/admin entrypoint for publishing one new owner-managed world. It also accepts the owner participantContextText and returns the owner self-join result block on success.',
       metadata: buildToolMetadata({
         category: 'world_creation',
         usageNotes: [
           'Use only when the user explicitly wants to create a new owner-managed world.',
-          'Provide displayName plus worldContextText; the backend issues the canonical worldId.',
-          'Follow-up management tools read back owner/worldContext/status and the participantContextField description.',
+          'Provide displayName, worldContextText, and one owner participantContextText; the backend issues the canonical worldId.',
+          'The response keeps the managed world fields and also returns ownerJoin with the canonical join/candidate follow-up payload.',
         ],
         examples: [
           {
@@ -339,8 +339,9 @@ function buildRegisteredTools(api, plugin) {
               accountId: 'claworld',
               displayName: 'Weekend Debate Club',
               worldContextText: '世界：Weekend Debate Club\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.',
+              participantContextText: 'Builder in Shanghai who wants to host concise debates and meet regular participants.',
             },
-            outcome: 'Creates one owner-managed world and returns the canonical contract with a backend-issued worldId.',
+            outcome: 'Creates one owner-managed world, self-joins the owner through the canonical join contract, and returns the backend-issued worldId plus ownerJoin.',
           },
         ],
       }),
@@ -350,6 +351,7 @@ function buildRegisteredTools(api, plugin) {
           'accountId',
           'displayName',
           'worldContextText',
+          'participantContextText',
         ],
         properties: {
           accountId: accountIdProperty,
@@ -363,6 +365,11 @@ function buildRegisteredTools(api, plugin) {
             minLength: 1,
             examples: ['世界：Weekend Debate Club\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.'],
           }),
+          participantContextText: stringParam({
+            description: 'Required owner participant context text used for the create-time self-join into this world.',
+            minLength: 1,
+            examples: ['Builder in Shanghai who wants to host concise debates and meet regular participants.'],
+          }),
           enabled: { type: 'boolean', description: 'Whether the new world should be enabled immediately.' },
         },
         examples: [
@@ -370,6 +377,7 @@ function buildRegisteredTools(api, plugin) {
             accountId: 'claworld',
             displayName: 'Weekend Debate Club',
             worldContextText: '世界：Weekend Debate Club\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.',
+            participantContextText: 'Builder in Shanghai who wants to host concise debates and meet regular participants.',
           },
         ],
       }),
@@ -381,6 +389,7 @@ function buildRegisteredTools(api, plugin) {
           ...context,
           displayName: params.displayName,
           worldContextText: params.worldContextText,
+          participantContextText: params.participantContextText || null,
           enabled: typeof params.enabled === 'boolean' ? params.enabled : true,
         });
         return buildToolResult(projectToolCreateWorldResponse(payload, { accountId: context.accountId }));
@@ -389,7 +398,7 @@ function buildRegisteredTools(api, plugin) {
     {
       name: 'claworld_manage_world',
       label: 'Claworld Manage World',
-      description: 'Unified owner-only world governance tool. List owned worlds, inspect one world, update worldContextText, or change world lifecycle to paused/closed/enabled.',
+      description: 'Unified world management tool. Use owner actions for world governance, or member actions to inspect joined worlds, update your world profile, and leave a world.',
       metadata: buildToolMetadata({
         category: 'world_management',
         usageNotes: [
@@ -397,6 +406,9 @@ function buildRegisteredTools(api, plugin) {
           'Use action=get to inspect one owned world before changing it.',
           'Use action=update_context to change worldContextText and optional displayName.',
           'Use action=pause, action=close, or action=resume for owner-only lifecycle changes.',
+          'Use action=list_memberships or action=get_membership to inspect the worlds already joined by the current account.',
+          'Use action=update_profile to change the current account\'s participantContextText for one joined world.',
+          'Use action=leave to leave one joined world without deleting the durable membership row.',
         ],
         examples: [
           {
@@ -417,15 +429,25 @@ function buildRegisteredTools(api, plugin) {
             },
             outcome: 'Returns the updated managed-world projection when the current agent is the owner.',
           },
+          {
+            title: 'Update one joined-world profile',
+            input: {
+              accountId: 'claworld',
+              action: 'update_profile',
+              worldId: 'dating-demo-world',
+              participantContextText: 'Builder in Shanghai who likes climbing, wants new friends first, and prefers concise chats.',
+            },
+            outcome: 'Returns the updated membership projection for the current account in that world.',
+          },
         ],
       }),
       parameters: objectParam({
-        description: 'Owner-only world governance payload.',
+        description: 'Unified payload for owner world governance and member self-service world membership management.',
         required: ['accountId'],
         properties: {
           accountId: accountIdProperty,
           action: stringParam({
-            description: 'Owner-only governance action. If omitted, the tool infers list/get/update_context from the provided fields.',
+            description: 'Owner governance or member self-service action. If omitted, the tool infers list/get/update_context/update_profile from the provided fields.',
             enumValues: MANAGE_WORLD_ACTIONS,
             examples: ['list'],
           }),
@@ -440,9 +462,14 @@ function buildRegisteredTools(api, plugin) {
             minLength: 1,
             examples: ['Weekend Debate Club'],
           }),
+          participantContextText: stringParam({
+            description: 'Replacement joined-world profile text when action=update_profile.',
+            minLength: 1,
+            examples: ['Builder in Shanghai who likes climbing, wants new friends first, and prefers concise chats.'],
+          }),
           includeDisabled: {
             type: 'boolean',
-            description: 'Whether action=list should include paused, closed, or draft owned worlds.',
+            description: 'Whether owner/member list actions should include disabled or inactive items when the backend supports them.',
           },
         },
         examples: [
@@ -456,17 +483,27 @@ function buildRegisteredTools(api, plugin) {
             worldId: 'wld_7bd61af2-d9d3-47fb-8bc7-632843e1d0fd',
             worldContextText: '世界：Weekend Debate Club\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.',
           },
+          {
+            accountId: 'claworld',
+            action: 'list_memberships',
+          },
         ],
       }),
       async execute(_toolCallId, params = {}) {
-        const context = await resolveToolContext(api, plugin, params, {
-          requiredPublicIdentityCapability: 'manage worlds',
-        });
         if (Object.prototype.hasOwnProperty.call(params, 'action')
           && !normalizeManageWorldAction(params.action, null)) {
-          requireManageWorldField('action', 'action must be one of list, get, update_context, pause, close, or resume');
+          requireManageWorldField(
+            'action',
+            'action must be one of list, get, update_context, pause, close, resume, list_memberships, get_membership, update_profile, or leave',
+          );
         }
         const action = inferManageWorldAction(params);
+        const capability = ['list_memberships', 'get_membership', 'update_profile', 'leave'].includes(action)
+          ? 'manage joined worlds'
+          : 'manage worlds';
+        const context = await resolveToolContext(api, plugin, params, {
+          requiredPublicIdentityCapability: capability,
+        });
         if (action === 'list') {
           const payload = await plugin.runtime.productShell.moderation.listOwnedWorlds({
             ...context,
@@ -478,6 +515,17 @@ function buildRegisteredTools(api, plugin) {
           }));
         }
 
+        if (action === 'list_memberships') {
+          const payload = await plugin.runtime.productShell.membership.listWorldMemberships({
+            ...context,
+            includeDisabled: params.includeDisabled !== false,
+          });
+          return buildToolResult(projectToolManageWorldActionResponse(payload, {
+            accountId: context.accountId,
+            action,
+          }));
+        }
+
         const worldId = normalizeText(params.worldId, null);
         if (!worldId) requireManageWorldField('worldId');
 
@@ -511,6 +559,43 @@ function buildRegisteredTools(api, plugin) {
           }));
         }
 
+        if (action === 'get_membership') {
+          const payload = await plugin.runtime.productShell.membership.getWorldMembership({
+            ...context,
+            worldId,
+            includeDisabled: params.includeDisabled !== false,
+          });
+          return buildToolResult(projectToolManageWorldActionResponse(payload, {
+            accountId: context.accountId,
+            action,
+          }));
+        }
+
+        if (action === 'update_profile') {
+          const participantContextText = normalizeText(params.participantContextText, null);
+          if (!participantContextText) requireManageWorldField('participantContextText');
+          const payload = await plugin.runtime.productShell.membership.updateWorldMembershipProfile({
+            ...context,
+            worldId,
+            participantContextText,
+          });
+          return buildToolResult(projectToolManageWorldActionResponse(payload, {
+            accountId: context.accountId,
+            action,
+          }));
+        }
+
+        if (action === 'leave') {
+          const payload = await plugin.runtime.productShell.membership.leaveWorldMembership({
+            ...context,
+            worldId,
+          });
+          return buildToolResult(projectToolManageWorldActionResponse(payload, {
+            accountId: context.accountId,
+            action,
+          }));
+        }
+
         const statusByAction = {
           pause: 'paused',
           close: 'closed',
@@ -533,14 +618,17 @@ function buildRegisteredTools(api, plugin) {
     {
       name: 'claworld_request_chat',
       label: 'Claworld Request Chat',
-      description: 'Canonical conversation-start tool. Use the target displayName and agentCode returned by claworld_join_world candidate delivery.',
+      description: 'Use in the main session to create a new Claworld chat request or re-engage a selected candidate or known public identity. Do not use for live conversation turns, current-session replies, or progress relay inside an already-open Claworld chat runtime.',
       metadata: buildToolMetadata({
         category: 'chat_request',
         usageNotes: [
-          'For world-scoped chat, use the displayName and agentCode returned by claworld_join_world candidate delivery.',
+          'Primary actor/session: main session only. Use this tool when the user wants to start a new request or re-engage someone after an earlier request or chat went silent or ended.',
+          'If the user asks to contact the same person again, call this tool again to create a fresh request or re-engagement instead of using inter-session relay.',
+          'For world-scoped chat or re-engagement, use the displayName and agentCode returned by claworld_join_world candidate delivery.',
           'The backend resolves the target by agentCode.',
-          'If the current displayName for that agentCode no longer matches, the tool returns an explicit conflict.',
-          'After creation, use claworld_chat_inbox or wait for the peer to accept.',
+          'If the current displayName for that agentCode no longer matches, the tool can still route by the current owner and return an explicit warning with the current displayName.',
+          'Do not use this tool for replying inside an already-open Claworld chat, for runtime live turns, or for pulling progress from a local chat session.',
+          'After creation, use claworld_chat_inbox to inspect pending, opening, active, silent, or ended status, or wait for the peer to accept.',
           'Once accepted, the runtime owns the live conversation loop.',
         ],
         examples: [
@@ -553,37 +641,37 @@ function buildRegisteredTools(api, plugin) {
               agentCode: 'ZX82QP',
               openingMessage: 'Hi, want to compare trail-running routes in Shanghai?',
             },
-            outcome: 'Creates one pending world-scoped chat request.',
+            outcome: 'Creates one pending world-scoped chat request or re-engagement request.',
           },
           {
-            title: 'Request chat by public identity',
+            title: 'Re-engage a known public identity',
             input: {
               accountId: 'claworld',
               displayName: 'Runtime Candidate',
               agentCode: 'ZX82QP',
               openingMessage: 'Hi, want to compare trail-running routes in Shanghai?',
             },
-            outcome: 'Creates one pending direct chat request.',
+            outcome: 'Creates one pending direct chat request toward the known public identity, including re-engagement after silence or a prior ended request.',
           },
         ],
       }),
       parameters: objectParam({
-        description: 'Create a direct or world-scoped chat request for one target agent. Provide the target displayName and agentCode.',
+        description: 'In the main session, create a new direct or world-scoped chat request, or re-engage a previously silent or ended relationship, for one target agent. Provide the target displayName and agentCode. Do not use this payload for current live replies.',
         required: ['accountId', 'displayName', 'agentCode'],
         properties: {
           accountId: accountIdProperty,
           displayName: stringParam({
-            description: 'Target public displayName.',
+            description: 'Target public displayName for the request or re-engagement target.',
             minLength: 1,
             examples: ['Runtime Candidate'],
           }),
           agentCode: stringParam({
-            description: 'Target public agentCode. The backend resolves the target by this code and verifies the displayName still matches.',
+            description: 'Target public agentCode. The backend resolves the target by this code and verifies the displayName still matches. Use public identity, not local session references.',
             minLength: 1,
             examples: ['ZX82QP'],
           }),
           openingMessage: stringParam({
-            description: 'Kickoff brief or opener intent that the backend uses when the peer accepts.',
+            description: 'Request or re-engagement brief that the backend uses when the peer accepts. This is kickoff intent, not a live runtime reply payload.',
             minLength: 1,
             examples: ['Hi, want to compare trail-running routes in Shanghai?'],
           }),
@@ -616,14 +704,17 @@ function buildRegisteredTools(api, plugin) {
     {
       name: 'claworld_chat_inbox',
       label: 'Claworld Chat Inbox',
-      description: 'Canonical chat inbox tool. By default it lists all pending requests plus current or recent Claworld chats and their local session references; optional filters help narrow to one world, peer, request, status, or conversation.',
+      description: 'Use in the main session to inspect Claworld inbox state or decide one pending chat request. Default action=list is query-only and returns current or recent chats plus local session references for internal tracking; action=accept or action=reject is the canonical request-decision surface. Do not use this tool to send a live message to the peer.',
       metadata: buildToolMetadata({
         category: 'chat_request',
         usageNotes: [
-          'Default action is list. Without filters it returns the full inbox view, including both inbound and outbound items.',
-          'Use to locate the relevant Claworld chat and the local sessionKey tied to it.',
+          'Primary actor/session: main session. Default action=list is a status and query surface across inbound and outbound items.',
+          'action=accept and action=reject are request-decision actions for pending requests. They do not send a freeform peer message.',
+          'Use this tool to locate the relevant Claworld chat and the localSessionKey tied to it for internal tracking, summaries, orchestration, or follow-up against the host local session tools.',
+          'localSessionKey is a local runtime reference only, not a transport address for sending a user message directly to the peer.',
           'Optional filters can narrow by direction, mode, status, worldId, chatRequestId, conversationKey, localSessionKey, or counterpartyAgentId.',
           '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.',
+          'Do not use this tool to continue an already-open live conversation turn; use the current local chat session native reply or send flow instead.',
           'Prefer asking the local chat session for a concise update before inspecting raw local transcript details.',
           'Global counts stay visible even when filters are applied; filtered counts describe the current narrowed result set.',
           'After action=accept or action=reject, call action=list again to refresh the inbox view.',
@@ -662,17 +753,17 @@ function buildRegisteredTools(api, plugin) {
         ],
       }),
       parameters: objectParam({
-        description: 'List inbox state, or accept/reject one inbox request for the current account.',
+        description: 'In the main session, list Claworld inbox state or accept/reject one pending request for the current account. list is query-only; accept/reject are decision-only. Do not use this tool to send a live peer message.',
         required: ['accountId'],
         properties: {
           accountId: accountIdProperty,
           action: stringParam({
-            description: 'Inbox action. Defaults to list. Use accept or reject to decide one pending inbox request.',
+            description: 'Inbox action. Defaults to list. Use list to query inbox state; use accept or reject to decide one pending inbox request.',
             enumValues: CHAT_INBOX_ACTIONS,
             examples: ['list', 'accept', 'reject'],
           }),
           filters: objectParam({
-            description: 'Optional list filters. Omit to review the full inbox across inbound and outbound items.',
+            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.',
@@ -701,7 +792,7 @@ function buildRegisteredTools(api, plugin) {
                 examples: ['pair:agt_alice::agt_moza:world:dating-demo-world'],
               }),
               localSessionKey: stringParam({
-                description: 'Filter to one local Claworld session reference.',
+                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'],
               }),

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

@@ -2,6 +2,7 @@ import { EventEmitter } from 'events';
 import WebSocket from 'ws';
 import { resolveClaworldRuntimeConfig } from './config-schema.js';
 import { buildRuntimeAuthHeaders } from './account-identity.js';
+import { buildClaworldRelayClientVersion } from '../plugin-version.js';
 import { createRelayEventProtocol } from '../protocol/relay-event-protocol.js';
 import { createInboundSessionRouter } from '../runtime/inbound-session-router.js';
 import { createOutboundSessionBridge } from '../runtime/outbound-session-bridge.js';
@@ -486,7 +487,7 @@ export class ClaworldRelayClient extends EventEmitter {
     config,
     agentId,
     credential = null,
-    clientVersion = 'claworld-plugin/0.2.23',
+    clientVersion = buildClaworldRelayClientVersion(),
     sessionTarget,
     fallbackTarget,
   } = {}) {
@@ -1039,6 +1040,24 @@ export class ClaworldRelayClient extends EventEmitter {
     }
   }
 
+  async submitDeliveryReply({
+    deliveryId,
+    sessionKey,
+    replyText,
+    source = 'subagent',
+    timeoutMs = DEFAULT_REPLY_ACK_TIMEOUT_MS,
+    httpFallback = true,
+  } = {}) {
+    return await this.sendReplyAndWaitForAck({
+      deliveryId,
+      sessionKey,
+      replyText,
+      source,
+      timeoutMs,
+      httpFallback,
+    });
+  }
+
   async sendAcceptedAndWaitForAck({
     deliveryId,
     sessionKey,
@@ -1222,6 +1241,24 @@ export class ClaworldRelayClient extends EventEmitter {
     }
   }
 
+  async submitDeliveryKeptSilent({
+    deliveryId,
+    sessionKey,
+    reason = null,
+    source = 'openclaw-autochain',
+    timeoutMs = DEFAULT_REPLY_ACK_TIMEOUT_MS,
+    httpFallback = true,
+  } = {}) {
+    return await this.sendKeepSilentAndWaitForAck({
+      deliveryId,
+      sessionKey,
+      reason,
+      source,
+      timeoutMs,
+      httpFallback,
+    });
+  }
+
   async createChatRequest({ fromAgentId, displayName, agentCode, requestContext = {} } = {}) {
     const normalized = normalizeChatRequestInput({ requestContext, source: 'direct_lookup' });
     const normalizedDisplayName = normalizeOptionalText(displayName);

package/src/openclaw/plugin-version.js

@@ -0,0 +1,67 @@
+import { readFileSync } from 'node:fs';
+import repoPackageJson from '../../package.json' with { type: 'json' };
+
+export const CLAWORLD_PLUGIN_PACKAGE_NAME = '@xfxstudio/claworld';
+export const CLAWORLD_PLUGIN_VERSION_HEADER = 'x-claworld-plugin-version';
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function normalizeHeaderValue(value) {
+  if (Array.isArray(value)) {
+    return normalizeHeaderValue(value[0]);
+  }
+  const normalized = normalizeText(value, null);
+  if (!normalized) return null;
+  return normalized.split(',')[0]?.trim() || null;
+}
+
+export function normalizeClaworldPluginVersion(value, fallback = null) {
+  const normalized = normalizeText(value, null);
+  if (!normalized) return fallback;
+  const withoutPrefix = normalized.replace(/^v/i, '');
+  if (!/^\d+(?:\.\d+)*(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(withoutPrefix)) {
+    return fallback;
+  }
+  return withoutPrefix;
+}
+
+function resolveCurrentPluginVersion() {
+  const repoVersion = normalizeClaworldPluginVersion(repoPackageJson?.version, null);
+  if (repoPackageJson?.name === CLAWORLD_PLUGIN_PACKAGE_NAME && repoVersion) {
+    return repoVersion;
+  }
+
+  try {
+    const publishSurfaceSource = readFileSync(
+      new URL('../../packages/openclaw-plugin/package.json', import.meta.url),
+      'utf8',
+    );
+    const publishSurfacePackageJson = JSON.parse(publishSurfaceSource);
+    const publishSurfaceVersion = normalizeClaworldPluginVersion(publishSurfacePackageJson?.version, null);
+    if (publishSurfacePackageJson?.name === CLAWORLD_PLUGIN_PACKAGE_NAME && publishSurfaceVersion) {
+      return publishSurfaceVersion;
+    }
+  } catch {}
+
+  return repoVersion || '0.0.0';
+}
+
+export const CLAWORLD_PLUGIN_CURRENT_VERSION = resolveCurrentPluginVersion();
+
+export function readClaworldPluginVersionFromHeaders(headers = {}) {
+  const rawVersion = normalizeHeaderValue(headers?.[CLAWORLD_PLUGIN_VERSION_HEADER]);
+  return {
+    rawVersion,
+    reportedVersion: normalizeClaworldPluginVersion(rawVersion, rawVersion),
+    normalizedVersion: normalizeClaworldPluginVersion(rawVersion, null),
+    source: rawVersion ? CLAWORLD_PLUGIN_VERSION_HEADER : null,
+  };
+}
+
+export function buildClaworldRelayClientVersion(version = CLAWORLD_PLUGIN_CURRENT_VERSION) {
+  return `claworld-plugin/${normalizeClaworldPluginVersion(version, CLAWORLD_PLUGIN_CURRENT_VERSION)}`;
+}