@xfxstudio/claworld 0.2.13 → 0.2.14

package/src/openclaw/plugin/register.js

@@ -348,18 +348,47 @@ function projectToolManageWorldActionResponse(payload = {}, { accountId = null,
   };
 }
 
-const PROFILE_ACTIONS = Object.freeze([
+const CHAT_INBOX_ACTIONS = Object.freeze([
+  'list',
+  'accept',
+  'reject',
+]);
+
+function normalizeChatInboxAction(value, fallback = null) {
+  const normalized = normalizeText(value, fallback);
+  return CHAT_INBOX_ACTIONS.includes(normalized) ? normalized : fallback;
+}
+
+function inferChatInboxAction(params = {}) {
+  return normalizeChatInboxAction(params.action, 'list');
+}
+
+function projectToolChatInboxActionResponse(payload = {}, { accountId = null, action = 'list' } = {}) {
+  const resolvedAction = normalizeChatInboxAction(action, 'list');
+  if (resolvedAction === 'list') {
+    return {
+      action: resolvedAction,
+      ...projectToolChatInboxResponse(payload, { accountId }),
+    };
+  }
+  return {
+    action: resolvedAction,
+    ...projectToolChatRequestMutationResponse(payload, { accountId }),
+  };
+}
+
+const ACCOUNT_ACTIONS = Object.freeze([
   'view',
   'update_identity',
 ]);
 
-function normalizeProfileAction(value, fallback = null) {
+function normalizeAccountAction(value, fallback = null) {
   const normalized = normalizeText(value, fallback);
-  return PROFILE_ACTIONS.includes(normalized) ? normalized : fallback;
+  return ACCOUNT_ACTIONS.includes(normalized) ? normalized : fallback;
 }
 
-function inferProfileAction(params = {}) {
-  const explicitAction = normalizeProfileAction(params.action, null);
+function inferAccountAction(params = {}) {
+  const explicitAction = normalizeAccountAction(params.action, null);
   if (explicitAction) return explicitAction;
   if (normalizeText(params.displayName, null)) return 'update_identity';
   return 'view';
@@ -420,34 +449,89 @@ function projectToolShareCard(payload = null) {
   };
 }
 
-function projectToolProfileResponse({
-  action = 'view',
+function projectToolAccountIdentityFields(identityPayload = null) {
+  const projectedIdentity = projectToolPublicIdentity(identityPayload);
+  if (projectedIdentity) {
+    return {
+      publicIdentity: projectedIdentity.publicIdentity,
+      recommendedDisplayName: projectedIdentity.recommendedDisplayName,
+      requiredAction: projectedIdentity.requiredAction,
+      nextAction: projectedIdentity.nextAction,
+      nextTool: projectedIdentity.nextTool,
+      missingFields: projectedIdentity.missingFields,
+      feedbackSummary: projectedIdentity.feedbackSummary,
+    };
+  }
+  return {
+    publicIdentity: null,
+    recommendedDisplayName: null,
+    requiredAction: null,
+    nextAction: null,
+    nextTool: null,
+    missingFields: [],
+    feedbackSummary: null,
+  };
+}
+
+function projectToolAccountViewResponse({
+  accountId = null,
+  pairingPayload = null,
+  identityPayload = null,
+} = {}) {
+  const identityReady = identityPayload?.ready === true;
+  const ready = pairingPayload?.status === 'paired' && identityReady;
+  const resolvedShareCard = identityPayload && Object.prototype.hasOwnProperty.call(identityPayload, 'shareCard')
+    ? projectToolShareCard(identityPayload.shareCard)
+    : undefined;
+  return {
+    action: 'view',
+    status: ready ? 'ready' : 'pending',
+    ready,
+    readiness: pairingPayload?.status === 'paired'
+      ? (identityReady ? 'paired_and_ready' : 'paired_but_identity_pending')
+      : 'installed_unactivated',
+    accountId: normalizeText(pairingPayload?.runtimeConfig?.accountId, normalizeText(accountId, null)),
+    reason: normalizeText(pairingPayload?.reason, null),
+    bindingSource: normalizeText(pairingPayload?.bindingSource, null),
+    activation: {
+      status: pairingPayload?.status === 'paired' ? 'ready' : 'pending',
+    },
+    relay: {
+      agentId: normalizeText(
+        pairingPayload?.runtimeConfig?.relay?.agentId,
+        normalizeText(pairingPayload?.relayAgent?.agentId, null),
+      ),
+      displayName: normalizeText(pairingPayload?.relayAgent?.displayName, null),
+      discoverable: pairingPayload?.relayAgent?.discoverable ?? null,
+      contactable: pairingPayload?.relayAgent?.contactable ?? null,
+      online: pairingPayload?.relayAgent?.online ?? null,
+      resolved: pairingPayload?.relayAgent?.resolved ?? null,
+      bindingStatus: pairingPayload?.status === 'paired' ? 'bound' : 'unactivated',
+    },
+    ...projectToolAccountIdentityFields(identityPayload),
+    ...(resolvedShareCard !== undefined ? { shareCard: resolvedShareCard } : {}),
+  };
+}
+
+function projectToolAccountMutationResponse({
+  action = 'update_identity',
   accountId = null,
   identityPayload = null,
   shareCard = undefined,
   runtimeActivation = null,
 } = {}) {
-  const projectedIdentity = projectToolPublicIdentity(identityPayload);
   const resolvedShareCard = shareCard !== undefined
     ? shareCard
     : (identityPayload && Object.prototype.hasOwnProperty.call(identityPayload, 'shareCard')
         ? projectToolShareCard(identityPayload.shareCard)
         : undefined);
-  const ready = projectedIdentity?.ready === true;
+  const ready = identityPayload?.ready === true;
   return {
     action,
     status: ready ? 'ready' : 'pending',
     ready,
     accountId: normalizeText(accountId, null),
-    ...(projectedIdentity || {
-      publicIdentity: null,
-      recommendedDisplayName: null,
-      requiredAction: null,
-      nextAction: null,
-      nextTool: null,
-      missingFields: [],
-      feedbackSummary: null,
-    }),
+    ...projectToolAccountIdentityFields(identityPayload),
     ...(resolvedShareCard !== undefined ? { shareCard: resolvedShareCard } : {}),
     ...(runtimeActivation ? { runtimeActivation } : {}),
     ...(action === 'update_identity'
@@ -485,7 +569,7 @@ function buildRegisteredTools(api, plugin) {
       metadata: buildToolMetadata({
         category: 'world_discovery',
         usageNotes: [
-          'Use after claworld_pair_agent when the user wants to browse worlds.',
+          'Use after claworld_account(action=view) when the user wants to browse worlds.',
           'After the user picks one world, call claworld_get_world_detail.',
         ],
         examples: [
@@ -908,82 +992,55 @@ function buildRegisteredTools(api, plugin) {
     {
       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.',
+      description: 'Canonical chat inbox tool. List pending requests plus current or recent Claworld chats and the local session references you can use to check progress, or accept/reject one inbox request from the same surface.',
       metadata: buildToolMetadata({
         category: 'chat_request',
         usageNotes: [
-          'Use to review pending inbound requests waiting for acceptance.',
+          'Default action is list. Use it 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.',
+          'After action=accept or action=reject, call action=list again to refresh the inbox view.',
         ],
         examples: [
           {
             title: 'Review inbound chat state',
             input: {
               accountId: 'claworld',
+              action: 'list',
               direction: 'inbound',
             },
             outcome: 'Returns pending requests plus related chats for the current account.',
           },
-        ],
-      }),
-      parameters: objectParam({
-        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 or outbound chat state from the current account perspective.',
-            enumValues: ['inbound', 'outbound'],
-            examples: ['inbound'],
-          }),
-        },
-        examples: [
-          {
-            accountId: 'claworld',
-            direction: 'inbound',
-          },
-        ],
-      }),
-      async execute(_toolCallId, params = {}) {
-        const context = await resolveToolContext(api, plugin, params);
-        const payload = await plugin.helpers.social.listChatInbox({
-          ...context,
-          direction: params.direction || null,
-        });
-        return buildToolResult(projectToolChatInboxResponse(payload, { accountId: context.accountId }));
-      },
-    },
-    {
-      name: 'claworld_accept_chat_request',
-      label: 'Claworld Accept Chat Request',
-      description: 'Canonical approval tool for one inbound chat request. After acceptance, the backend prepares kickoff and the runtime owns the live session.',
-      metadata: buildToolMetadata({
-        category: 'chat_request',
-        usageNotes: [
-          '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: [
           {
-            title: 'Accept one inbound request',
+            title: 'Accept one inbound request from the inbox',
             input: {
               accountId: 'claworld',
+              action: 'accept',
               chatRequestId: 'req_demo_1',
             },
-            outcome: 'Marks the request accepted and returns kickoff progress.',
+            outcome: 'Marks the request accepted and returns kickoff progress from the same inbox surface.',
           },
         ],
       }),
       parameters: objectParam({
-        description: 'Accept one inbound chat request for the current account.',
-        required: ['accountId', 'chatRequestId'],
+        description: 'List inbox state, or accept/reject one inbox request for the current account.',
+        required: ['accountId'],
         properties: {
           accountId: accountIdProperty,
+          action: stringParam({
+            description: 'Inbox action. Defaults to list. Use accept or reject to decide one pending inbox request.',
+            enumValues: CHAT_INBOX_ACTIONS,
+            examples: ['list', 'accept', 'reject'],
+          }),
+          direction: stringParam({
+            description: 'Filter to inbound or outbound chat state from the current account perspective. Used with action=list.',
+            enumValues: ['inbound', 'outbound'],
+            examples: ['inbound'],
+          }),
           chatRequestId: stringParam({
-            description: 'Canonical chat request id returned by claworld_chat_inbox pendingRequests.',
+            description: 'Canonical chat request id returned by claworld_chat_inbox pendingRequests. Required for action=accept or action=reject.',
             minLength: 1,
             examples: ['req_demo_1'],
           }),
@@ -991,65 +1048,46 @@ function buildRegisteredTools(api, plugin) {
         examples: [
           {
             accountId: 'claworld',
-            chatRequestId: 'req_demo_1',
-          },
-        ],
-      }),
-      async execute(_toolCallId, params = {}) {
-        const context = await resolveToolContext(api, plugin, params);
-        const payload = await plugin.helpers.social.acceptChatRequest({
-          ...context,
-          chatRequestId: params.chatRequestId,
-        });
-        return buildToolResult(projectToolChatRequestMutationResponse(payload, { accountId: context.accountId }));
-      },
-    },
-    {
-      name: 'claworld_reject_chat_request',
-      label: 'Claworld Reject Chat Request',
-      description: 'Canonical rejection tool for one inbound chat request. Use this when the current account explicitly declines the request instead of accepting it.',
-      metadata: buildToolMetadata({
-        category: 'chat_request',
-        usageNotes: [
-          'Use the chatRequestId returned by claworld_list_chat_requests.',
-          'Use only for inbound requests that the current account wants to reject.',
-        ],
-        examples: [
-          {
-            title: 'Reject one inbound request',
-            input: {
-              accountId: 'claworld',
-              chatRequestId: 'req_demo_1',
-            },
-            outcome: 'Marks the request rejected and returns the closed request projection.',
+            action: 'list',
+            direction: 'inbound',
           },
-        ],
-      }),
-      parameters: objectParam({
-        description: 'Reject one inbound chat request for the current account.',
-        required: ['accountId', 'chatRequestId'],
-        properties: {
-          accountId: accountIdProperty,
-          chatRequestId: stringParam({
-            description: 'Canonical chat request id returned by claworld_list_chat_requests.',
-            minLength: 1,
-            examples: ['req_demo_1'],
-          }),
-        },
-        examples: [
           {
             accountId: 'claworld',
+            action: 'accept',
             chatRequestId: 'req_demo_1',
           },
         ],
       }),
       async execute(_toolCallId, params = {}) {
         const context = await resolveToolContext(api, plugin, params);
-        const payload = await plugin.helpers.social.rejectChatRequest({
+        const action = inferChatInboxAction(params);
+        if (action === 'accept' || action === 'reject') {
+          const chatRequestId = normalizeText(params.chatRequestId, null);
+          if (!chatRequestId) {
+            requireManageWorldField('chatRequestId', `chatRequestId is required for action=${action}`);
+          }
+          const payload = action === 'accept'
+            ? await plugin.helpers.social.acceptChatRequest({
+                ...context,
+                chatRequestId,
+              })
+            : await plugin.helpers.social.rejectChatRequest({
+                ...context,
+                chatRequestId,
+              });
+          return buildToolResult(projectToolChatInboxActionResponse(payload, {
+            accountId: context.accountId,
+            action,
+          }));
+        }
+        const payload = await plugin.helpers.social.listChatInbox({
           ...context,
-          chatRequestId: params.chatRequestId,
+          direction: params.direction || null,
         });
-        return buildToolResult(projectToolChatRequestMutationResponse(payload, { accountId: context.accountId }));
+        return buildToolResult(projectToolChatInboxActionResponse(payload, {
+          accountId: context.accountId,
+          action,
+        }));
       },
     },
     {
@@ -1210,123 +1248,24 @@ function buildRegisteredTools(api, plugin) {
       },
     },
     {
-      name: 'claworld_pair_agent',
-      label: 'Claworld Pair Agent',
-      description: 'Bootstrap and diagnostics tool. Ensure the current Claworld account resolves to a usable relay binding before world discovery or request flows.',
-      metadata: buildToolMetadata({
-        category: 'bootstrap',
-        usageNotes: [
-          'Run once after install or when channel binding looks unhealthy.',
-          'Use before any world or chat-request flow if the current account has not been validated yet.',
-        ],
-        examples: [
-          {
-            title: 'Validate the managed account binding',
-            input: {
-              accountId: 'claworld',
-            },
-            outcome: 'Returns the resolved relay identity and binding source.',
-          },
-        ],
-      }),
-      parameters: objectParam({
-        description: 'Validate or bootstrap the relay binding for one Claworld account.',
-        required: ['accountId'],
-        properties: {
-          accountId: accountIdProperty,
-        },
-        examples: [
-          {
-            accountId: 'claworld',
-          },
-        ],
-      }),
-      async execute(_toolCallId, params = {}) {
-        const cfg = await loadCurrentConfig(api);
-        const accountId = normalizeText(params.accountId, plugin.config.defaultAccountId(cfg) || null);
-        const runtimeConfig = plugin.config.resolveRuntimeConfig(cfg, accountId);
-        const payload = await plugin.helpers.pairing.ensureAgentPairing({
-          cfg,
-          accountId,
-          runtimeConfig,
-        });
-        const pairedAgentId = payload.runtimeConfig?.relay?.agentId || payload.relayAgent?.agentId || null;
-        const publicIdentity = await plugin.runtime.productShell.profile.getPublicIdentity({
-          cfg,
-          accountId,
-          runtimeConfig: payload.runtimeConfig || runtimeConfig,
-          agentId: pairedAgentId,
-        });
-        const ready = payload.status === 'paired' && publicIdentity?.ready === true;
-        const readiness = payload.status === 'paired'
-          ? (publicIdentity?.ready === true ? 'paired_and_ready' : 'paired_but_identity_pending')
-          : 'installed_unactivated';
-        return buildToolResult({
-          status: ready ? 'ready' : 'pending',
-          ready,
-          readiness,
-          reason: payload.reason || null,
-          requiredAction: publicIdentity?.requiredAction || (ready ? null : 'set_public_identity'),
-          nextAction: publicIdentity?.nextAction || (ready ? 'continue_claworld_flow' : 'set_public_identity'),
-          nextTool: publicIdentity?.nextTool || (ready ? null : 'claworld_profile'),
-          missingFields: Array.isArray(publicIdentity?.missingFields) ? publicIdentity.missingFields : [],
-          accountId: payload.runtimeConfig?.accountId || accountId,
-          bindingSource: payload.bindingSource || null,
-          activation: {
-            status: payload.status === 'paired' ? 'ready' : 'pending',
-          },
-          relay: {
-            agentId: payload.runtimeConfig?.relay?.agentId || payload.relayAgent?.agentId || null,
-            displayName: payload.relayAgent?.displayName || null,
-            discoverable: payload.relayAgent?.discoverable ?? null,
-            contactable: payload.relayAgent?.contactable ?? null,
-            online: payload.relayAgent?.online ?? null,
-            resolved: payload.relayAgent?.resolved ?? null,
-            bindingStatus: payload.status === 'paired' ? 'bound' : 'unactivated',
-          },
-          publicIdentity: publicIdentity
-            ? {
-              status: publicIdentity.status || null,
-              ready: publicIdentity.ready ?? null,
-              displayIdentity: publicIdentity.publicIdentity?.displayIdentity || null,
-              displayName: publicIdentity.publicIdentity?.displayName || null,
-              code: publicIdentity.publicIdentity?.code || null,
-              nextAction: publicIdentity.nextAction || null,
-              nextTool: publicIdentity.nextTool || null,
-              missingFields: Array.isArray(publicIdentity.missingFields) ? publicIdentity.missingFields : [],
-              recommendedDisplayName: publicIdentity.recommendedDisplayName || null,
-              feedbackSummary: publicIdentity.feedbackSummary && typeof publicIdentity.feedbackSummary === 'object'
-                ? {
-                  totalLikesReceived: Number(publicIdentity.feedbackSummary.totalLikesReceived || 0),
-                  totalDislikesReceived: Number(publicIdentity.feedbackSummary.totalDislikesReceived || 0),
-                  totalLikesGiven: Number(publicIdentity.feedbackSummary.totalLikesGiven || 0),
-                  totalDislikesGiven: Number(publicIdentity.feedbackSummary.totalDislikesGiven || 0),
-                }
-                : null,
-            }
-            : null,
-        });
-      },
-    },
-    {
-      name: 'claworld_profile',
-      label: 'Claworld Profile',
-      description: 'View or update the paired Claworld public profile. This surface covers public identity readiness and, when requested, generates a temporary public identity card for sharing.',
+      name: 'claworld_account',
+      label: 'Claworld Account',
+      description: 'Canonical account surface. View current relay binding plus public identity readiness, or update the public display identity for the current Claworld account.',
       metadata: buildToolMetadata({
-        category: 'profile',
+        category: 'account',
         usageNotes: [
-          'Default action is view; omit action to inspect the current public identity state.',
+          'Default action is view. It runs the readiness/binding check and returns the current public identity state.',
           'Use action=update_identity after the user confirms a public-facing display name.',
           'Set generateShareCard=true to return a temporary public identity card URL.',
         ],
         examples: [
           {
-            title: 'View the current profile state',
+            title: 'View the current account state',
             input: {
               accountId: 'claworld',
               action: 'view',
             },
-            outcome: 'Returns the current public identity and readiness state.',
+            outcome: 'Returns readiness, relay binding, and public identity for the current account.',
           },
           {
             title: 'Update public identity and return a share card',
@@ -1341,13 +1280,13 @@ function buildRegisteredTools(api, plugin) {
         ],
       }),
       parameters: objectParam({
-        description: 'View or update the public profile for one Claworld account.',
+        description: 'View or update the current Claworld account state.',
         required: ['accountId'],
         properties: {
           accountId: accountIdProperty,
           action: stringParam({
-            description: 'Profile action. Defaults to view; inferred as update_identity when displayName is present.',
-            enumValues: PROFILE_ACTIONS,
+            description: 'Account action. Defaults to view; inferred as update_identity when displayName is present.',
+            enumValues: ACCOUNT_ACTIONS,
             examples: ['view', 'update_identity'],
           }),
           displayName: stringParam({
@@ -1378,13 +1317,13 @@ function buildRegisteredTools(api, plugin) {
         ],
       }),
       async execute(_toolCallId, params = {}) {
-        const context = await resolveToolContext(api, plugin, params, { bindRuntime: false });
-        const action = inferProfileAction(params);
+        const action = inferAccountAction(params);
         const generateShareCard = typeof params.generateShareCard === 'boolean'
           ? params.generateShareCard
           : action === 'update_identity';
 
         if (action === 'update_identity') {
+          const context = await resolveToolContext(api, plugin, params, { bindRuntime: false });
           const displayName = normalizeText(params.displayName, null);
           if (!displayName) {
             requireManageWorldField('displayName', 'displayName is required for action=update_identity');
@@ -1395,7 +1334,7 @@ function buildRegisteredTools(api, plugin) {
             generateShareCard,
             expiresInSeconds: params.expiresInSeconds ?? null,
           });
-          return buildToolResult(projectToolProfileResponse({
+          return buildToolResult(projectToolAccountMutationResponse({
             action,
             accountId: context.accountId,
             identityPayload: payload,
@@ -1403,15 +1342,27 @@ function buildRegisteredTools(api, plugin) {
           }));
         }
 
-        const payload = await plugin.runtime.productShell.profile.getPublicIdentity({
-          ...context,
+        const cfg = await loadCurrentConfig(api);
+        const accountId = normalizeText(params.accountId, plugin.config.defaultAccountId(cfg) || null);
+        const runtimeConfig = plugin.config.resolveRuntimeConfig(cfg, accountId);
+        const pairingPayload = await plugin.helpers.pairing.ensureAgentPairing({
+          cfg,
+          accountId,
+          runtimeConfig,
+        });
+        const pairedAgentId = pairingPayload.runtimeConfig?.relay?.agentId || pairingPayload.relayAgent?.agentId || null;
+        const identityPayload = await plugin.runtime.productShell.profile.getPublicIdentity({
+          cfg,
+          accountId,
+          runtimeConfig: pairingPayload.runtimeConfig || runtimeConfig,
+          agentId: pairedAgentId,
           generateShareCard,
           expiresInSeconds: params.expiresInSeconds ?? null,
         });
-        return buildToolResult(projectToolProfileResponse({
-          action,
-          accountId: context.accountId,
-          identityPayload: payload,
+        return buildToolResult(projectToolAccountViewResponse({
+          accountId,
+          pairingPayload,
+          identityPayload,
         }));
       },
     },

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

@@ -1,6 +1,5 @@
 import { EventEmitter } from 'events';
 import WebSocket from 'ws';
-import { v4 as uuidv4 } from 'uuid';
 import { resolveClaworldRuntimeConfig } from './config-schema.js';
 import { buildRuntimeAuthHeaders } from './account-identity.js';
 import { createRelayEventProtocol } from '../protocol/relay-event-protocol.js';
@@ -60,8 +59,12 @@ function normalizeOptionalText(value) {
   return normalized || null;
 }
 
-function resolveClientMessageId(value = null) {
-  return normalizeOptionalText(value) || `cmsg_${uuidv4()}`;
+function requireClientMessageId(value = null) {
+  const normalized = normalizeOptionalText(value);
+  if (!normalized) {
+    throw new Error('claworld relay clientMessageId is required for POST /v1/messages');
+  }
+  return normalized;
 }
 
 function buildReplyAckTimeoutError({ deliveryId, timeoutMs, context = {} } = {}) {
@@ -584,7 +587,7 @@ export class ClaworldRelayClient extends EventEmitter {
     config,
     agentId,
     credential = null,
-    clientVersion = 'claworld-plugin/0.2.8',
+    clientVersion = 'claworld-plugin/0.2.14',
     sessionTarget,
     fallbackTarget,
   } = {}) {
@@ -1376,7 +1379,7 @@ export class ClaworldRelayClient extends EventEmitter {
   }
 
   async deliverMessage({ fromAgentId, targetAgentId, clientMessageId = null, payload = {}, conversation = {} } = {}) {
-    const resolvedClientMessageId = resolveClientMessageId(clientMessageId);
+    const resolvedClientMessageId = requireClientMessageId(clientMessageId);
     const result = await this.requestJson('/v1/messages', {
       method: 'POST',
       headers: buildRuntimeAuthHeaders(this.runtimeConfig, { 'content-type': 'application/json' }),