@xfxstudio/claworld 0.2.9 → 0.2.10-beta.1

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,18 @@ 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?.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 +107,15 @@ function currentManagedIdentityInput({ cfg = {}, accountId = null } = {}) {
     };
   }
 
-  const currentCode = normalizeText(
-    inspected?.registration?.agentCode,
-    normalizeText(inspected?.localAgent?.agentCode, null),
+  const currentDisplayName = normalizeText(
+    inspected?.name,
+    normalizeText(
+      inspected?.registration?.displayName,
+      normalizeText(inspected?.localAgent?.displayName, null),
+    ),
   );
-  return isCanonicalAgentHandle(currentCode)
-    ? { code: currentCode }
+  return currentDisplayName
+    ? { name: currentDisplayName }
     : {};
 }
 
@@ -139,18 +125,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,
   };
 }
 
@@ -183,11 +169,17 @@ function applyManagedAccountName({ cfg = {}, accountId, name } = {}) {
 }
 
 function resolveManagedOptionsFromContext({ cfg = {}, accountId = null, input = {}, overrides = {} } = {}) {
+  const normalizedInput = ensureObject(input);
+  const resolvedInput = { ...normalizedInput };
+  delete resolvedInput.name;
   return resolveClaworldManagedRuntimeOptions({
     cfg,
     accountId: normalizeText(accountId, DEFAULT_CLAWORLD_ACCOUNT_ID),
-    input,
-    overrides,
+    input: resolvedInput,
+    overrides: {
+      ...overrides,
+      ...(normalizeText(normalizedInput.name, null) ? { displayName: normalizedInput.name } : {}),
+    },
   });
 }
 
@@ -207,9 +199,9 @@ async function applyManagedOnboardingConfig({
   const noteLines = [
     `Bound local agent/account: ${managedOptions.agentId}`,
     `Remote backend: ${managedOptions.serverUrl}`,
-    managedOptions.registrationAgentCode
-      ? `Bootstrap mode: registration (${managedOptions.registrationAgentCode})`
-      : 'Bootstrap mode: appToken/manual binding',
+    managedOptions.appToken
+      ? 'Activation state: ready via configured appToken'
+      : 'Activation state: pending until claworld_update_public_identity runs',
     managedOptions.manageWorkspace
       ? 'This flow refreshes plugin-side config and the dedicated claworld workspace contract. It does not start a backend service.'
       : 'This flow refreshes plugin-side config and binds claworld onto the existing local agent. It does not start a backend service.',

package/src/openclaw/plugin/register.js

@@ -18,6 +18,11 @@ 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';
 
@@ -52,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;
@@ -157,12 +178,12 @@ function withToolErrorBoundary(toolName, execute) {
   };
 }
 
-async function resolveToolContext(api, plugin, params = {}) {
+async function resolveToolContext(api, plugin, params = {}, { bindRuntime = true } = {}) {
   const cfg = await loadCurrentConfig(api);
   const accountId = normalizeText(params.accountId, plugin.config.defaultAccountId(cfg) || null);
   const runtimeConfig = plugin.config.resolveRuntimeConfig(cfg, accountId);
 
-  if (typeof plugin.helpers?.resolveToolRuntimeContext === 'function') {
+  if (bindRuntime && typeof plugin.helpers?.resolveToolRuntimeContext === 'function') {
     return await plugin.helpers.resolveToolRuntimeContext({
       cfg,
       accountId,
@@ -553,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 }));
       },
@@ -1009,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,
@@ -1110,24 +1127,118 @@ function buildRegisteredTools(api, plugin) {
           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: payload.status,
+          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_update_public_identity'),
+          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,
-            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,
+            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_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, { bindRuntime: false });
+        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, { bindRuntime: false });
+        const payload = await plugin.runtime.productShell.profile.updatePublicIdentity({
+          ...context,
+          displayName: params.displayName,
         });
+        return buildToolResult(payload);
       },
     },
   ].map((tool) => ({