@xfxstudio/claworld 0.2.15 → 0.2.17

package/src/openclaw/plugin/register.js

@@ -1,10 +1,7 @@
 import { createClaworldChannelPlugin } from './claworld-channel-plugin.js';
 import {
-  projectToolChatInboxResponse,
   projectToolChatRequestMutationResponse,
   projectToolCreateWorldResponse,
-  projectToolManagedWorldResponse,
-  projectToolOwnedWorldsResponse,
   projectToolWorldList,
   projectToolFeedbackSubmissionResponse,
   projectToolJoinWorldResponse,
@@ -12,83 +9,37 @@ import {
 } from '../runtime/tool-contracts.js';
 import { CLAWORLD_TOOL_CONTRACT_VERSION } from '../runtime/tool-inventory.js';
 import { setClaworldRuntime } from './runtime.js';
-import {
-  buildPublicErrorPayload,
-  createRuntimeBoundaryError,
-  logRuntimeBoundary,
-  normalizeRuntimeBoundaryError,
-} from '../../lib/runtime-errors.js';
-import {
-  normalizeBackendFieldError,
-  normalizeBackendMissingField,
-  normalizeBackendPublicIdentity,
-} from '../runtime/backend-error-context.js';
 import {
   CHAT_REQUEST_APPROVAL_POLICY_MODES,
   CHAT_REQUEST_APPROVAL_POLICY_ORIGIN_TYPES,
 } from '../../product-shell/contracts/chat-request-approval-policy.js';
-
-const INTERNAL_REQUESTER_SESSION_KEY_PARAM = '__claworldRequesterSessionKey';
-
-function normalizeText(value, fallback = null) {
-  if (value == null) return fallback;
-  const normalized = String(value).trim();
-  return normalized || fallback;
-}
-
-function normalizeObject(value, fallback = null) {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return fallback;
-  return value;
-}
-
-function normalizePublicFieldError(fieldError = {}) {
-  const fieldId = normalizeText(fieldError.fieldId, null);
-  const message = normalizeText(fieldError.message, null);
-  const code = normalizeText(fieldError.code, null);
-  if (!fieldId && !message && !code) return null;
-  return {
-    ...(fieldId ? { fieldId } : {}),
-    ...(message ? { message } : {}),
-    ...(code ? { code } : {}),
-  };
-}
-
-function buildPublicToolErrorExtras(error) {
-  const context = normalizeObject(error?.context, null);
-  if (!context) return null;
-
-  const httpStatus = Number(context.httpStatus);
-  const backendCode = normalizeText(context.backendCode, null);
-  const backendMessage = normalizeText(context.backendMessage, null);
-  const fieldErrors = Array.isArray(context.fieldErrors)
-    ? 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;
-}
+import {
+  ACCOUNT_ACTIONS,
+  arrayParam,
+  booleanParam,
+  buildToolMetadata,
+  buildToolResult,
+  CHAT_INBOX_ACTIONS,
+  inferAccountAction,
+  inferChatInboxAction,
+  inferManageWorldAction,
+  INTERNAL_REQUESTER_SESSION_KEY_PARAM,
+  integerParam,
+  loadCurrentConfig,
+  MANAGE_WORLD_ACTIONS,
+  normalizeManageWorldAction,
+  normalizeObject,
+  normalizeText,
+  objectParam,
+  projectToolAccountMutationResponse,
+  projectToolAccountViewResponse,
+  projectToolChatInboxActionResponse,
+  projectToolManageWorldActionResponse,
+  requireManageWorldField,
+  resolveToolContext,
+  stringParam,
+  withToolErrorBoundary,
+} from './register-tooling.js';
 
 function buildClaworldStatusRoute(plugin) {
   return {
@@ -118,471 +69,6 @@ function buildClaworldStatusRoute(plugin) {
   };
 }
 
-async function loadCurrentConfig(api) {
-  if (api?.config && typeof api.config.loadConfig === 'function') {
-    return await api.config.loadConfig();
-  }
-  if (api?.runtime?.config && typeof api.runtime.config.loadConfig === 'function') {
-    return await api.runtime.config.loadConfig();
-  }
-  if (api?.config && typeof api.config === 'object') {
-    return api.config;
-  }
-  return {};
-}
-
-function buildToolResult(payload) {
-  return {
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify(payload, null, 2),
-      },
-    ],
-  };
-}
-
-function buildToolErrorResult(toolName, error) {
-  const normalized = normalizeRuntimeBoundaryError(error, {
-    code: 'claworld_tool_execution_failed',
-    category: 'runtime',
-    publicMessage: 'tool execution failed',
-    recoverable: true,
-  });
-  return buildToolResult({
-    status: 'error',
-    tool: toolName,
-    ...buildPublicErrorPayload(normalized, {
-      errorType: 'claworld_tool_failed',
-      fallbackMessage: 'tool execution failed',
-      exposeMessage: normalized.status < 500 || Boolean(normalized.publicMessage),
-      extra: buildPublicToolErrorExtras(normalized),
-    }),
-  });
-}
-
-function withToolErrorBoundary(toolName, execute) {
-  return async (toolCallId, params = {}) => {
-    try {
-      return await execute(toolCallId, params);
-    } catch (error) {
-      const normalized = logRuntimeBoundary(console, `[claworld:tool:${toolName}] execution failed`, error, {
-        tool: toolName,
-      }, {
-        includeStack: false,
-        fallback: {
-          code: 'claworld_tool_execution_failed',
-          category: 'runtime',
-          publicMessage: 'tool execution failed',
-          recoverable: true,
-        },
-      });
-      return buildToolErrorResult(toolName, normalized);
-    }
-  };
-}
-
-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 (bindRuntime && typeof plugin.helpers?.resolveToolRuntimeContext === 'function') {
-    return await plugin.helpers.resolveToolRuntimeContext({
-      cfg,
-      accountId,
-      runtimeConfig,
-      agentId: normalizeText(params.agentId, runtimeConfig.relay?.agentId || null),
-      requesterSessionKey: normalizeText(params[INTERNAL_REQUESTER_SESSION_KEY_PARAM], null),
-    });
-  }
-
-  const agentId = normalizeText(params.agentId, runtimeConfig.relay?.agentId || null);
-  return {
-    cfg,
-    accountId,
-    runtimeConfig,
-    agentId,
-    requesterSessionKey: normalizeText(params[INTERNAL_REQUESTER_SESSION_KEY_PARAM], null),
-  };
-}
-
-function cloneMetadataValue(value) {
-  return value == null ? value : JSON.parse(JSON.stringify(value));
-}
-
-function stringParam({
-  description = null,
-  minLength = null,
-  enumValues = null,
-  pattern = null,
-  examples = [],
-} = {}) {
-  return {
-    type: 'string',
-    ...(description ? { description } : {}),
-    ...(Number.isInteger(minLength) && minLength > 0 ? { minLength } : {}),
-    ...(Array.isArray(enumValues) && enumValues.length > 0 ? { enum: enumValues } : {}),
-    ...(pattern ? { pattern } : {}),
-    ...(Array.isArray(examples) && examples.length > 0 ? { examples } : {}),
-  };
-}
-
-function integerParam({
-  description = null,
-  minimum = null,
-  maximum = null,
-  examples = [],
-} = {}) {
-  return {
-    type: 'integer',
-    ...(description ? { description } : {}),
-    ...(Number.isInteger(minimum) ? { minimum } : {}),
-    ...(Number.isInteger(maximum) ? { maximum } : {}),
-    ...(Array.isArray(examples) && examples.length > 0 ? { examples } : {}),
-  };
-}
-
-function booleanParam({
-  description = null,
-  defaultValue = null,
-} = {}) {
-  return {
-    type: 'boolean',
-    ...(description ? { description } : {}),
-    ...(typeof defaultValue === 'boolean' ? { default: defaultValue } : {}),
-  };
-}
-
-function objectParam({
-  description = null,
-  properties = {},
-  required = [],
-  additionalProperties = false,
-  examples = [],
-} = {}) {
-  return {
-    type: 'object',
-    additionalProperties,
-    ...(description ? { description } : {}),
-    ...(Array.isArray(required) && required.length > 0 ? { required } : {}),
-    properties,
-    ...(Array.isArray(examples) && examples.length > 0 ? { examples: examples.map(cloneMetadataValue) } : {}),
-  };
-}
-
-function arrayParam({
-  description = null,
-  items = {},
-  maxItems = null,
-  examples = [],
-} = {}) {
-  return {
-    type: 'array',
-    items,
-    ...(description ? { description } : {}),
-    ...(Number.isInteger(maxItems) ? { maxItems } : {}),
-    ...(Array.isArray(examples) && examples.length > 0 ? { examples: examples.map(cloneMetadataValue) } : {}),
-  };
-}
-
-function buildToolMetadata({
-  category,
-  usageNotes = [],
-  examples = [],
-} = {}) {
-  return {
-    surface: 'canonical_public',
-    canonical: true,
-    category: normalizeText(category, 'general'),
-    usageNotes: Array.isArray(usageNotes) ? usageNotes.filter(Boolean) : [],
-    examples: Array.isArray(examples)
-      ? examples.map((example) => cloneMetadataValue(example)).filter(Boolean)
-      : [],
-  };
-}
-
-const MANAGE_WORLD_ACTIONS = Object.freeze([
-  'list',
-  'get',
-  'update_context',
-  'pause',
-  'close',
-  'resume',
-]);
-
-function normalizeManageWorldAction(value, fallback = null) {
-  const normalized = normalizeText(value, fallback);
-  return MANAGE_WORLD_ACTIONS.includes(normalized) ? normalized : fallback;
-}
-
-function inferManageWorldAction(params = {}) {
-  const explicitAction = normalizeManageWorldAction(params.action, null);
-  if (explicitAction) return explicitAction;
-  if (!normalizeText(params.worldId, null)) return 'list';
-  if (normalizeText(params.worldContextText, null) || normalizeText(params.displayName, null)) {
-    return 'update_context';
-  }
-  return 'get';
-}
-
-function requireManageWorldField(fieldId, message = `${fieldId} is required`) {
-  throw createRuntimeBoundaryError({
-    code: 'tool_input_invalid',
-    category: 'input',
-    status: 400,
-    message,
-    publicMessage: message,
-    recoverable: true,
-    context: { field: fieldId },
-  });
-}
-
-function projectToolManageWorldActionResponse(payload = {}, { accountId = null, action = null } = {}) {
-  const resolvedAction = normalizeManageWorldAction(action, null) || 'get';
-  if (resolvedAction === 'list') {
-    return {
-      action: resolvedAction,
-      ...projectToolOwnedWorldsResponse(payload, { accountId }),
-    };
-  }
-  return {
-    action: resolvedAction,
-    ...projectToolManagedWorldResponse(payload, { accountId }),
-  };
-}
-
-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',
-  'update_chat_policy',
-]);
-
-function normalizeAccountAction(value, fallback = null) {
-  const normalized = normalizeText(value, fallback);
-  return ACCOUNT_ACTIONS.includes(normalized) ? normalized : fallback;
-}
-
-function inferAccountAction(params = {}) {
-  const explicitAction = normalizeAccountAction(params.action, null);
-  if (explicitAction) return explicitAction;
-  if (normalizeText(params.displayName, null)) return 'update_identity';
-  if (normalizeObject(params.chatRequestApprovalPolicy, null)) return 'update_chat_policy';
-  return 'view';
-}
-
-function projectToolPublicIdentity(payload = null) {
-  if (!payload || typeof payload !== 'object') return null;
-  return {
-    status: payload.status || null,
-    ready: payload.ready ?? null,
-    publicIdentity: payload.publicIdentity && typeof payload.publicIdentity === 'object'
-      ? {
-          status: payload.publicIdentity.status || null,
-          displayIdentity: payload.publicIdentity.displayIdentity || null,
-          displayName: payload.publicIdentity.displayName || null,
-          code: payload.publicIdentity.code || null,
-          confirmedAt: payload.publicIdentity.confirmedAt || null,
-          updatedAt: payload.publicIdentity.updatedAt || null,
-        }
-      : null,
-    recommendedDisplayName: payload.recommendedDisplayName || null,
-    requiredAction: payload.requiredAction || null,
-    nextAction: payload.nextAction || null,
-    nextTool: payload.nextTool || null,
-    missingFields: Array.isArray(payload.missingFields) ? payload.missingFields : [],
-    feedbackSummary: payload.feedbackSummary && typeof payload.feedbackSummary === 'object'
-      ? {
-          totalLikesReceived: Number(payload.feedbackSummary.totalLikesReceived || 0),
-          totalDislikesReceived: Number(payload.feedbackSummary.totalDislikesReceived || 0),
-          totalLikesGiven: Number(payload.feedbackSummary.totalLikesGiven || 0),
-          totalDislikesGiven: Number(payload.feedbackSummary.totalDislikesGiven || 0),
-        }
-      : null,
-  };
-}
-
-function projectToolShareCard(payload = null) {
-  const card = payload?.card && typeof payload.card === 'object' ? payload.card : null;
-  const imageUrl = normalizeText(card?.imageUrl, normalizeText(payload?.imageUrl, null));
-  const downloadUrl = normalizeText(card?.downloadUrl, normalizeText(payload?.downloadUrl, imageUrl));
-  const templateId = normalizeText(card?.templateId, normalizeText(payload?.templateId, null));
-  const expiresAt = normalizeText(card?.expiresAt, normalizeText(payload?.expiresAt, null));
-  const description = normalizeText(card?.description, normalizeText(payload?.description, null));
-  if (!imageUrl && !downloadUrl && !templateId && !expiresAt && !description) {
-    return {
-      status: normalizeText(payload?.status, 'unavailable'),
-      reason: normalizeText(payload?.reason, null),
-      message: normalizeText(payload?.message, null),
-    };
-  }
-  return {
-    status: normalizeText(payload?.status, 'ready'),
-    imageUrl,
-    downloadUrl,
-    templateId,
-    expiresAt,
-    description,
-  };
-}
-
-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 projectToolChatRequestApprovalPolicy(payload = null) {
-  const policy = normalizeObject(payload, null);
-  if (!policy) return null;
-  return {
-    agentId: normalizeText(policy.agentId, null),
-    schemaVersion: Number.isInteger(policy.schemaVersion) ? policy.schemaVersion : null,
-    syncedAt: normalizeText(policy.syncedAt, null),
-    credentialId: normalizeText(policy.credentialId, null),
-    source: normalizeObject(policy.source, {})
-      ? {
-          channel: normalizeText(policy.source?.channel, null),
-          integration: normalizeText(policy.source?.integration, null),
-          accountId: normalizeText(policy.source?.accountId, null),
-        }
-      : {},
-    policy: normalizeObject(policy.policy, {})
-      ? {
-          mode: normalizeText(policy.policy?.mode, null),
-          blocks: {
-            originTypes: Array.isArray(policy.policy?.blocks?.originTypes) ? policy.policy.blocks.originTypes : [],
-            worldIds: Array.isArray(policy.policy?.blocks?.worldIds) ? policy.policy.blocks.worldIds : [],
-          },
-        }
-      : 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),
-    chatRequestApprovalPolicy: projectToolChatRequestApprovalPolicy(identityPayload?.chatRequestApprovalPolicy),
-    ...(resolvedShareCard !== undefined ? { shareCard: resolvedShareCard } : {}),
-  };
-}
-
-function projectToolAccountMutationResponse({
-  action = 'update_identity',
-  accountId = null,
-  identityPayload = null,
-  shareCard = undefined,
-  runtimeActivation = null,
-} = {}) {
-  const resolvedShareCard = shareCard !== undefined
-    ? shareCard
-    : (identityPayload && Object.prototype.hasOwnProperty.call(identityPayload, 'shareCard')
-        ? projectToolShareCard(identityPayload.shareCard)
-        : undefined);
-  const ready = identityPayload?.ready === true;
-  return {
-    action,
-    status: ready ? 'ready' : 'pending',
-    ready,
-    accountId: normalizeText(accountId, null),
-    ...projectToolAccountIdentityFields(identityPayload),
-    chatRequestApprovalPolicy: projectToolChatRequestApprovalPolicy(identityPayload?.chatRequestApprovalPolicy),
-    ...(resolvedShareCard !== undefined ? { shareCard: resolvedShareCard } : {}),
-    ...(runtimeActivation ? { runtimeActivation } : {}),
-    ...(action === 'update_identity'
-      ? {
-          updated: resolvedShareCard && resolvedShareCard.status === 'ready'
-            ? ['publicIdentity', 'shareCard']
-            : ['publicIdentity'],
-        }
-      : action === 'update_chat_policy'
-        ? {
-            updated: ['chatRequestApprovalPolicy'],
-          }
-      : {}),
-  };
-}
-
 function buildRegisteredTools(api, plugin) {
   const accountIdProperty = stringParam({
     description: 'Claworld account id to execute the tool against. In managed installs this is usually the dedicated claworld account.',
@@ -807,7 +293,7 @@ function buildRegisteredTools(api, plugin) {
         category: 'world_creation',
         usageNotes: [
           'Use only when the user explicitly wants to create a new owner-managed world.',
-          'Provide displayName plus worldContextText.',
+          'Provide displayName plus worldContextText; the backend issues the canonical worldId.',
           'Follow-up management tools read back owner/worldContext/status and the participantContextField description.',
         ],
         examples: [
@@ -818,7 +304,7 @@ function buildRegisteredTools(api, plugin) {
               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.',
             },
-            outcome: 'Creates one draft owner-managed world and returns the canonical world contract.',
+            outcome: 'Creates one owner-managed world and returns the canonical contract with a backend-issued worldId.',
           },
         ],
       }),
@@ -888,15 +374,15 @@ function buildRegisteredTools(api, plugin) {
             input: {
               accountId: 'claworld',
               action: 'update_context',
-              worldId: 'ugc-weekend-debate-club',
-              worldContextText: '世界：Weekend Debate Club [ugc-weekend-debate-club]\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.',
+              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.',
             },
             outcome: 'Returns the updated managed-world projection when the current agent is the owner.',
           },
         ],
       }),
       parameters: objectParam({
-        description: 'Owner-only world governance payload. action=list replaces the old list_owned_worlds tool.',
+        description: 'Owner-only world governance payload.',
         required: ['accountId'],
         properties: {
           accountId: accountIdProperty,
@@ -909,7 +395,7 @@ function buildRegisteredTools(api, plugin) {
           worldContextText: stringParam({
             description: 'Replacement canonical world context text for update_context.',
             minLength: 1,
-            examples: ['世界：Weekend Debate Club [ugc-weekend-debate-club]\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.'],
+            examples: ['世界：Weekend Debate Club\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.'],
           }),
           displayName: stringParam({
             description: 'Optional new display name when action=update_context.',
@@ -929,8 +415,8 @@ function buildRegisteredTools(api, plugin) {
           {
             accountId: 'claworld',
             action: 'update_context',
-            worldId: 'ugc-weekend-debate-club',
-            worldContextText: '世界：Weekend Debate Club [ugc-weekend-debate-club]\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.',
+            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.',
           },
         ],
       }),
@@ -1007,11 +493,13 @@ function buildRegisteredTools(api, plugin) {
     {
       name: 'claworld_request_chat',
       label: 'Claworld Request Chat',
-      description: 'Canonical conversation-start tool. Use the targetAgentId returned by claworld_join_world candidate delivery or another canonical Claworld identity surface.',
+      description: 'Canonical conversation-start tool. Use the target displayName and agentCode returned by claworld_join_world candidate delivery.',
       metadata: buildToolMetadata({
         category: 'chat_request',
         usageNotes: [
-          'For world-scoped chat, use the targetAgentId returned by claworld_join_world.',
+          'For world-scoped chat, 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.',
           'Once accepted, the runtime owns the live conversation loop.',
         ],
@@ -1021,22 +509,38 @@ function buildRegisteredTools(api, plugin) {
             input: {
               accountId: 'claworld',
               worldId: 'dating-demo-world',
-              targetAgentId: 'agt_runtime_candidate',
+              displayName: 'Runtime Candidate',
+              agentCode: 'ZX82QP',
               openingMessage: 'Hi, want to compare trail-running routes in Shanghai?',
             },
             outcome: 'Creates one pending world-scoped chat request.',
           },
+          {
+            title: 'Request chat by 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.',
+          },
         ],
       }),
       parameters: objectParam({
-        description: 'Create a direct or world-scoped chat request for one target agent.',
-        required: ['accountId', 'targetAgentId'],
+        description: 'Create a direct or world-scoped chat request for one target agent. Provide the target displayName and agentCode.',
+        required: ['accountId', 'displayName', 'agentCode'],
         properties: {
           accountId: accountIdProperty,
-          targetAgentId: stringParam({
-            description: 'Canonical target agentId. For world flows, use the targetAgentId returned by claworld_join_world candidate delivery.',
+          displayName: stringParam({
+            description: 'Target public displayName.',
             minLength: 1,
-            examples: ['agt_runtime_candidate'],
+            examples: ['Runtime Candidate'],
+          }),
+          agentCode: stringParam({
+            description: 'Target public agentCode. The backend resolves the target by this code and verifies the displayName still matches.',
+            minLength: 1,
+            examples: ['ZX82QP'],
           }),
           openingMessage: stringParam({
             description: 'Kickoff brief or opener intent that the backend uses when the peer accepts.',
@@ -1049,7 +553,8 @@ function buildRegisteredTools(api, plugin) {
           {
             accountId: 'claworld',
             worldId: 'dating-demo-world',
-            targetAgentId: 'agt_runtime_candidate',
+            displayName: 'Runtime Candidate',
+            agentCode: 'ZX82QP',
             openingMessage: 'Hi, want to compare trail-running routes in Shanghai?',
           },
         ],
@@ -1058,7 +563,8 @@ function buildRegisteredTools(api, plugin) {
         const context = await resolveToolContext(api, plugin, params);
         const payload = await plugin.helpers.social.requestChat({
           ...context,
-          targetAgentId: params.targetAgentId,
+          displayName: params.displayName,
+          agentCode: params.agentCode,
           openingMessage: params.openingMessage || null,
           worldId: params.worldId || null,
         });
@@ -1332,6 +838,7 @@ function buildRegisteredTools(api, plugin) {
         usageNotes: [
           '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.',
+          'Use action=update_profile to store one global plain-text profile for the current account.',
           'Set generateShareCard=true to return a temporary public identity card URL.',
         ],
         examples: [
@@ -1353,6 +860,15 @@ function buildRegisteredTools(api, plugin) {
             },
             outcome: 'Persists the display name, keeps the stable code, and returns a temporary share-card URL.',
           },
+          {
+            title: 'Update the global profile',
+            input: {
+              accountId: 'claworld',
+              action: 'update_profile',
+              profile: '喜欢慢节奏介绍和小范围世界，也愿意先让 agent 帮我做初步认识。🙂',
+            },
+            outcome: 'Stores the current account profile text. Pass an empty string to clear it.',
+          },
           {
             title: 'Update the inbound chat policy',
             input: {
@@ -1375,15 +891,19 @@ function buildRegisteredTools(api, plugin) {
         properties: {
           accountId: accountIdProperty,
           action: stringParam({
-            description: 'Account action. Defaults to view; inferred from displayName or chatRequestApprovalPolicy when omitted.',
+            description: 'Account action. Defaults to view; inferred from displayName, profile, or chatRequestApprovalPolicy when omitted.',
             enumValues: ACCOUNT_ACTIONS,
-            examples: ['view', 'update_identity', 'update_chat_policy'],
+            examples: ['view', 'update_identity', 'update_profile', 'update_chat_policy'],
           }),
           displayName: stringParam({
             description: 'Public-facing display name. Required for action=update_identity. # is reserved and must not appear here.',
             minLength: 1,
             examples: ['Moza', '小发发'],
           }),
+          profile: stringParam({
+            description: 'Global plain-text profile for this account. Maximum 200 characters. Use an empty string to clear it. HTML is not supported.',
+            examples: ['喜欢慢节奏介绍和小范围世界，也愿意先让 agent 帮我做初步认识。🙂'],
+          }),
           chatRequestApprovalPolicy: chatRequestApprovalPolicyProperty,
           generateShareCard: booleanParam({
             description: 'When true, return a temporary public identity card URL. Defaults to false for view and true for update_identity.',
@@ -1405,6 +925,11 @@ function buildRegisteredTools(api, plugin) {
             displayName: '小发发',
             generateShareCard: true,
           },
+          {
+            accountId: 'claworld',
+            action: 'update_profile',
+            profile: '喜欢慢节奏介绍和小范围世界，也愿意先让 agent 帮我做初步认识。🙂',
+          },
           {
             accountId: 'claworld',
             action: 'update_chat_policy',
@@ -1440,6 +965,22 @@ function buildRegisteredTools(api, plugin) {
           }));
         }
 
+        if (action === 'update_profile') {
+          const context = await resolveToolContext(api, plugin, params);
+          if (!Object.prototype.hasOwnProperty.call(params, 'profile')) {
+            requireManageWorldField('profile', 'profile is required for action=update_profile');
+          }
+          const payload = await plugin.runtime.productShell.profile.updateProfile({
+            ...context,
+            profile: params.profile == null ? '' : String(params.profile),
+          });
+          return buildToolResult(projectToolAccountMutationResponse({
+            action,
+            accountId: context.accountId,
+            identityPayload: payload,
+          }));
+        }
+
         if (action === 'update_chat_policy') {
           const context = await resolveToolContext(api, plugin, params);
           const chatRequestApprovalPolicy = normalizeObject(params.chatRequestApprovalPolicy, null);
@@ -1463,20 +1004,47 @@ function buildRegisteredTools(api, plugin) {
         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,
+          runtimeConfig,
+          agentId: runtimeConfig.relay?.agentId || null,
           generateShareCard,
           expiresInSeconds: params.expiresInSeconds ?? null,
         });
+        const pairedAgentId = identityPayload?.agentId || runtimeConfig.relay?.agentId || null;
+        const relayAgent = pairedAgentId
+          ? await plugin.helpers.pairing.resolveAgentIdentity({
+            cfg,
+            accountId,
+            runtimeConfig,
+            agentId: pairedAgentId,
+          })
+          : null;
+        const hasConfiguredAppToken = Boolean(
+          runtimeConfig.appToken
+          || runtimeConfig.relay?.appToken
+          || runtimeConfig.relay?.credentialToken,
+        );
+        const pairingPayload = {
+          status: hasConfiguredAppToken ? 'paired' : 'unpaired',
+          reason: hasConfiguredAppToken
+            ? (pairedAgentId ? null : 'missing_agent_id')
+            : 'missing_app_token',
+          bindingSource: hasConfiguredAppToken
+            ? 'configured_app_token'
+            : (runtimeConfig.registration?.enabled === true ? 'registration_pending' : 'unbound'),
+          runtimeConfig: pairedAgentId
+            ? {
+              ...runtimeConfig,
+              relay: {
+                ...(runtimeConfig.relay && typeof runtimeConfig.relay === 'object' ? runtimeConfig.relay : {}),
+                agentId: pairedAgentId,
+              },
+            }
+            : runtimeConfig,
+          relayAgent,
+        };
         return buildToolResult(projectToolAccountViewResponse({
           accountId,
           pairingPayload,