@xfxstudio/claworld 0.2.8 → 0.2.10-beta.0

package/src/openclaw/plugin/onboarding.js

@@ -7,27 +7,16 @@ import {
   resolveClaworldManagedRuntimeOptions,
 } from './managed-config.js';
 import {
-  LOCAL_AGENT_BOOTSTRAP_SCHEMA,
   defaultClaworldAccountId,
   inspectClaworldChannelAccount,
   listClaworldAccountIds,
 } from './config-schema.js';
-import { parseAgentHandle } from '../../lib/agent-address.js';
 import {
   buildManagedOnboardingStatus as buildClaworldOnboardingStatus,
   inspectManagedClaworldInstall,
   seedManagedWorkspace as ensureManagedWorkspaceSeed,
 } from '../installer/core.js';
 
-const LOCAL_AGENT_CODE_REGEX = new RegExp(
-  LOCAL_AGENT_BOOTSTRAP_SCHEMA?.properties?.agentCode?.pattern || '^[A-Za-z0-9._:+~-]+$',
-  'i',
-);
-
-function isCanonicalAgentHandle(value) {
-  return Boolean(parseAgentHandle(value)?.canonical);
-}
-
 function collectUnsupportedSetupFlags(input = {}) {
   const unsupported = [];
   const flagMap = [
@@ -69,7 +58,7 @@ function validateClaworldSetupInput({ cfg = {}, accountId = null, input = {} } =
   const unsupportedFlags = collectUnsupportedSetupFlags(input);
   if (unsupportedFlags.length > 0) {
     return (
-      'Claworld setup only supports --name, --http-url/--url, --app-token, and --code. ' +
+      'Claworld setup only supports --name, --http-url/--url, and --app-token. ' +
       `Unsupported flag(s): ${unsupportedFlags.join(', ')}.`
     );
   }
@@ -92,24 +81,15 @@ function validateClaworldSetupInput({ cfg = {}, accountId = null, input = {} } =
     }
   }
 
-  const explicitRegistrationAgentCode = normalizeText(input.code, null);
-  const existingRegistrationAgentCode = normalizeText(
-    inspected?.registration?.agentCode,
-    normalizeText(inspected?.localAgent?.agentCode, null),
+  const registrationDisplayName = normalizeText(
+    input.name,
+    normalizeText(
+      inspected?.registration?.displayName,
+      normalizeText(inspected?.localAgent?.displayName, null),
+    ),
   );
-  const registrationAgentCode = explicitRegistrationAgentCode
-    || (isCanonicalAgentHandle(existingRegistrationAgentCode) ? existingRegistrationAgentCode : null);
-  if (!appToken && !explicitRegistrationAgentCode && existingRegistrationAgentCode && !isCanonicalAgentHandle(existingRegistrationAgentCode)) {
-    return 'Existing Claworld registration.agentCode is legacy/raw. Re-run setup with --code <local@namespace> so the namespace stays explicit.';
-  }
-  if (!appToken && !registrationAgentCode) {
-    return 'Claworld identity handle is required unless you already have an appToken. Use --code <local@namespace> or --app-token <token>.';
-  }
-  if (!appToken && explicitRegistrationAgentCode && !LOCAL_AGENT_CODE_REGEX.test(explicitRegistrationAgentCode)) {
-    return 'Claworld identity handle must match ^[A-Za-z0-9._:+~-]+(?:@[A-Za-z0-9._:+~-]+)?$.';
-  }
-  if (!appToken && explicitRegistrationAgentCode && !isCanonicalAgentHandle(explicitRegistrationAgentCode)) {
-    return 'Claworld identity handle must use canonical local@namespace syntax (for example "xiaofafa@robin").';
+  if (!appToken && !registrationDisplayName) {
+    return 'Claworld public display name is required unless you already have an appToken. Use --name <display-name> or --app-token <token>.';
   }
 
   return null;
@@ -124,12 +104,12 @@ function currentManagedIdentityInput({ cfg = {}, accountId = null } = {}) {
     };
   }
 
-  const currentCode = normalizeText(
-    inspected?.registration?.agentCode,
-    normalizeText(inspected?.localAgent?.agentCode, null),
+  const currentDisplayName = normalizeText(
+    inspected?.registration?.displayName,
+    normalizeText(inspected?.localAgent?.displayName, null),
   );
-  return isCanonicalAgentHandle(currentCode)
-    ? { code: currentCode }
+  return currentDisplayName
+    ? { name: currentDisplayName }
     : {};
 }
 
@@ -139,18 +119,18 @@ async function collectManagedIdentityInput({ cfg = {}, prompter, accountId = nul
     return currentInput;
   }
 
-  const code = await prompter.text({
-    message: 'Choose a unique Claworld identity handle',
-    initialValue: currentInput.code || '',
-    placeholder: 'xiaofafa@robin',
+  const name = await prompter.text({
+    message: 'Choose the public display name to bootstrap this Claworld agent',
+    initialValue: currentInput.name || '',
+    placeholder: 'Claworld Agent',
     validate: (value) => {
-      const message = validateClaworldSetupInput({ input: { code: value } });
+      const message = validateClaworldSetupInput({ input: { name: value } });
       return message || undefined;
     },
   });
 
   return {
-    code,
+    name,
   };
 }
 
@@ -207,8 +187,8 @@ async function applyManagedOnboardingConfig({
   const noteLines = [
     `Bound local agent/account: ${managedOptions.agentId}`,
     `Remote backend: ${managedOptions.serverUrl}`,
-    managedOptions.registrationAgentCode
-      ? `Bootstrap mode: registration (${managedOptions.registrationAgentCode})`
+    managedOptions.registrationDisplayName
+      ? `Bootstrap mode: registration (${managedOptions.registrationDisplayName})`
       : 'Bootstrap mode: appToken/manual binding',
     managedOptions.manageWorkspace
       ? 'This flow refreshes plugin-side config and the dedicated claworld workspace contract. It does not start a backend service.'

package/src/openclaw/plugin/register.js

@@ -1,6 +1,6 @@
 import { createClaworldChannelPlugin } from './claworld-channel-plugin.js';
 import {
-  projectToolChatRequestListResponse,
+  projectToolChatInboxResponse,
   projectToolChatRequestMutationResponse,
   projectToolCreateWorldResponse,
   projectToolManagedWorldResponse,
@@ -18,6 +18,13 @@ import {
   logRuntimeBoundary,
   normalizeRuntimeBoundaryError,
 } from '../../lib/runtime-errors.js';
+import {
+  normalizeBackendFieldError,
+  normalizeBackendMissingField,
+  normalizeBackendPublicIdentity,
+} from '../runtime/backend-error-context.js';
+
+const INTERNAL_REQUESTER_SESSION_KEY_PARAM = '__claworldRequesterSessionKey';
 
 function normalizeText(value, fallback = null) {
   if (value == null) return fallback;
@@ -50,14 +57,30 @@ function buildPublicToolErrorExtras(error) {
   const backendCode = normalizeText(context.backendCode, null);
   const backendMessage = normalizeText(context.backendMessage, null);
   const fieldErrors = Array.isArray(context.fieldErrors)
-    ? context.fieldErrors.map((fieldError) => normalizePublicFieldError(fieldError)).filter(Boolean)
+    ? context.fieldErrors
+      .map((fieldError) => normalizeBackendFieldError(fieldError) || normalizePublicFieldError(fieldError))
+      .filter(Boolean)
+    : [];
+  const requiredAction = normalizeText(context.requiredAction, null);
+  const nextAction = normalizeText(context.nextAction, null);
+  const nextTool = normalizeText(context.nextTool, null);
+  const missingFields = Array.isArray(context.missingFields)
+    ? context.missingFields
+      .map((field) => normalizeBackendMissingField(field))
+      .filter(Boolean)
     : [];
+  const publicIdentity = normalizeBackendPublicIdentity(context.publicIdentity);
 
   const extra = {
     ...(Number.isInteger(httpStatus) && httpStatus > 0 ? { httpStatus } : {}),
     ...(backendCode ? { backendCode } : {}),
     ...(backendMessage ? { backendMessage } : {}),
     ...(fieldErrors.length > 0 ? { fieldErrors } : {}),
+    ...(requiredAction ? { requiredAction } : {}),
+    ...(nextAction ? { nextAction } : {}),
+    ...(nextTool ? { nextTool } : {}),
+    ...(missingFields.length > 0 ? { missingFields } : {}),
+    ...(publicIdentity ? { publicIdentity } : {}),
   };
 
   return Object.keys(extra).length > 0 ? extra : null;
@@ -166,6 +189,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 +199,7 @@ async function resolveToolContext(api, plugin, params = {}) {
     accountId,
     runtimeConfig,
     agentId,
+    requesterSessionKey: normalizeText(params[INTERNAL_REQUESTER_SESSION_KEY_PARAM], null),
   };
 }
 
@@ -549,7 +574,7 @@ function buildRegisteredTools(api, plugin) {
           ...context,
           displayName: params.displayName,
           worldContextText: params.worldContextText,
-          enabled: params.enabled === true,
+          enabled: typeof params.enabled === 'boolean' ? params.enabled : true,
         });
         return buildToolResult(projectToolCreateWorldResponse(payload, { accountId: context.accountId }));
       },
@@ -704,7 +729,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: [
@@ -758,33 +783,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'],
           }),
@@ -798,11 +826,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 }));
       },
     },
     {
@@ -812,7 +840,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: [
@@ -832,7 +860,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'],
           }),
@@ -1002,10 +1030,6 @@ function buildRegisteredTools(api, plugin) {
                 description: 'Optional peer agentId related to the issue.',
                 examples: ['agt_runtime_candidate'],
               }),
-              targetAgentCode: stringParam({
-                description: 'Optional compatibility agentCode for the peer.',
-                examples: ['runtimecandidate@relay.local'],
-              }),
               tags: arrayParam({
                 description: 'Short labels used for moderation and triage filtering.',
                 maxItems: 10,
@@ -1103,6 +1127,15 @@ function buildRegisteredTools(api, plugin) {
           accountId,
           runtimeConfig,
         });
+        const pairedAgentId = payload.runtimeConfig?.relay?.agentId || payload.relayAgent?.agentId || null;
+        const publicIdentity = pairedAgentId
+          ? await plugin.runtime.productShell.profile.getPublicIdentity({
+            cfg,
+            accountId,
+            runtimeConfig,
+            agentId: pairedAgentId,
+          })
+          : null;
         return buildToolResult({
           status: payload.status,
           reason: payload.reason || null,
@@ -1110,19 +1143,92 @@ function buildRegisteredTools(api, plugin) {
           bindingSource: payload.bindingSource || null,
           relay: {
             agentId: payload.runtimeConfig?.relay?.agentId || payload.relayAgent?.agentId || null,
-            agentCode: payload.relayAgent?.agentCode || null,
-            relayLocalCode: payload.relayAgent?.relayLocalCode || null,
-            address: payload.relayAgent?.address || null,
-            domain: payload.relayAgent?.domain || 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,
           },
+          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_get_public_identity',
+      label: 'Claworld Get Public Identity',
+      description: 'Read the current public identity state for the paired Claworld agent. Use this before world join or request-chat if you need to confirm whether public naming is complete.',
+      metadata: buildToolMetadata({
+        category: 'bootstrap',
+        usageNotes: [
+          'Use when pair_agent indicates public identity is still pending.',
+          'Use before requesting a public-name confirmation from the user.',
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Read the current public identity state for one Claworld account.',
+        required: ['accountId'],
+        properties: {
+          accountId: accountIdProperty,
+        },
+      }),
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.runtime.productShell.profile.getPublicIdentity(context);
+        return buildToolResult(payload);
+      },
+    },
+    {
+      name: 'claworld_update_public_identity',
+      label: 'Claworld Update Public Identity',
+      description: 'Set or update the public display name for the paired Claworld agent. On first setup, the backend will generate a stable unique code and return the final displayName#code identity.',
+      metadata: buildToolMetadata({
+        category: 'bootstrap',
+        usageNotes: [
+          'Use after the user confirms a public-facing name.',
+          'On first setup, this generates the stable public code and completes identity readiness.',
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Update the public display name for one Claworld account.',
+        required: ['accountId', 'displayName'],
+        properties: {
+          accountId: accountIdProperty,
+          displayName: stringParam({
+            description: 'Public-facing display name. # is reserved and must not appear here.',
+            minLength: 1,
+            examples: ['Moza', '小发发'],
+          }),
+        },
+      }),
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.runtime.productShell.profile.updatePublicIdentity({
+          ...context,
+          displayName: params.displayName,
+        });
+        return buildToolResult(payload);
+      },
+    },
   ].map((tool) => ({
     ...tool,
     execute: withToolErrorBoundary(tool.name, tool.execute),
@@ -1133,6 +1239,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));
   }