@xfxstudio/claworld 2026.4.16-testing.1 → 2026.4.16-testing.2

package/src/openclaw/plugin/register.js

@@ -0,0 +1,1616 @@
+import { createClaworldChannelPlugin } from './claworld-channel-plugin.js';
+import {
+  projectToolChatRequestMutationResponse,
+  projectToolCandidateFeedResponse,
+  projectToolCreateWorldResponse,
+  projectToolFeedbackSubmissionResponse,
+  projectToolJoinWorldResponse,
+  projectToolWorldDetail,
+  projectToolWorldList,
+  projectToolWorldMemberSearchResponse,
+  projectToolWorldSearchResponse,
+} from '../runtime/tool-contracts.js';
+import { CLAWORLD_TOOL_CONTRACT_VERSION } from '../runtime/tool-inventory.js';
+import { setClaworldRuntime } from './runtime.js';
+import {
+  CHAT_REQUEST_APPROVAL_POLICY_MODES,
+  CHAT_REQUEST_APPROVAL_POLICY_ORIGIN_TYPES,
+} from '../../product-shell/contracts/chat-request-approval-policy.js';
+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 {
+    method: 'GET',
+    path: '/plugins/claworld/status',
+    auth: 'gateway',
+    match: 'exact',
+    async handler(_req, res) {
+      const payload = plugin.status?.getSnapshot?.() || {
+        ok: true,
+        pluginId: plugin.id || 'claworld',
+      };
+      if (typeof res?.status === 'function' && typeof res?.json === 'function') {
+        res.status(200).json(payload);
+        return true;
+      }
+      if (typeof res?.setHeader === 'function') {
+        res.statusCode = 200;
+        res.setHeader('content-type', 'application/json; charset=utf-8');
+      }
+      if (typeof res?.end === 'function') {
+        res.end(JSON.stringify(payload));
+        return true;
+      }
+      return payload;
+    },
+  };
+}
+
+const CHAT_INBOX_FILTER_DIRECTIONS = Object.freeze([
+  'inbound',
+  'outbound',
+]);
+const CHAT_INBOX_FILTER_MODES = Object.freeze([
+  'direct',
+  'world',
+]);
+const CHAT_INBOX_FILTER_STATUSES = Object.freeze([
+  'pending',
+  'opening',
+  'ending',
+  'active',
+  'silent',
+  'kickoff_failed',
+  'ended',
+]);
+
+function normalizeChatInboxListFiltersInput(params = {}) {
+  const source = normalizeObject(params.filters, {}) || {};
+  const normalized = {
+    direction: normalizeText(source.direction ?? params.direction, null),
+    mode: normalizeText(source.mode, null),
+    status: normalizeText(source.status, null),
+    worldId: normalizeText(source.worldId, null),
+    chatRequestId: normalizeText(source.chatRequestId, null),
+    conversationKey: normalizeText(source.conversationKey, null),
+    localSessionKey: normalizeText(source.localSessionKey, null),
+    counterpartyAgentId: normalizeText(source.counterpartyAgentId, null),
+  };
+  return Object.fromEntries(
+    Object.entries(normalized).filter(([, value]) => value != null),
+  );
+}
+
+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.',
+    minLength: 1,
+    examples: ['claworld'],
+  });
+  const chatRequestApprovalPolicyProperty = objectParam({
+    description: 'Backend-managed inbound chat-request policy for this account.',
+    required: ['mode'],
+    properties: {
+      mode: stringParam({
+        description: 'Policy mode controlling which new inbound chat requests auto-accept.',
+        enumValues: CHAT_REQUEST_APPROVAL_POLICY_MODES,
+        examples: ['open', 'manual_review'],
+      }),
+      blocks: objectParam({
+        description: 'Optional deny rules applied before the allow mode is evaluated.',
+        properties: {
+          originTypes: arrayParam({
+            description: 'Canonical request origin types that should always be rejected.',
+            items: stringParam({
+              enumValues: CHAT_REQUEST_APPROVAL_POLICY_ORIGIN_TYPES,
+            }),
+            examples: [['world_broadcast']],
+          }),
+          worldIds: arrayParam({
+            description: 'World ids that should always be rejected.',
+            items: stringParam({}),
+            examples: [['dating-demo-world']],
+          }),
+        },
+      }),
+    },
+    examples: [
+      {
+        mode: 'trusted_or_world',
+        blocks: {
+          originTypes: ['world_broadcast'],
+          worldIds: [],
+        },
+      },
+    ],
+  });
+  const worldIdProperty = stringParam({
+    description: 'Canonical world id returned by claworld_search_worlds or claworld_get_world_detail.',
+    minLength: 1,
+    examples: ['dating-demo-world'],
+  });
+  const profileObjectProperty = (description, examples = []) => objectParam({
+    description,
+    additionalProperties: true,
+    examples,
+  });
+  const broadcastAudienceValues = ['members', 'admins', 'admins_and_owner'];
+  const broadcastReplyPolicyValues = ['zero', 'at_most_one'];
+  const broadcastConfigProperty = objectParam({
+    description: 'Optional world broadcast config for owner update_context. This controls whether announcement broadcast is enabled and who receives it.',
+    properties: {
+      enabled: booleanParam({
+        description: 'Whether owner announcement broadcast is enabled for this world.',
+      }),
+      audience: stringParam({
+        description: 'Default broadcast audience for this world.',
+        enumValues: broadcastAudienceValues,
+        examples: ['members'],
+      }),
+      replyPolicy: stringParam({
+        description: 'Reply expectation for announcement kickoff semantics.',
+        enumValues: broadcastReplyPolicyValues,
+        examples: ['zero'],
+      }),
+      excludeSelf: booleanParam({
+        description: 'Whether owner broadcast excludes the sender from recipient targets.',
+      }),
+    },
+    examples: [{
+      enabled: true,
+      audience: 'members',
+      replyPolicy: 'zero',
+      excludeSelf: true,
+    }],
+  });
+
+  return [
+    {
+      name: 'claworld_search_worlds',
+      label: 'Claworld Search Worlds',
+      description: 'Canonical world discovery tool. Use it either to browse worlds with no query or to search worlds by topic, intent, hobby, location, or other free-form keywords.',
+      metadata: buildToolMetadata({
+        category: 'world_discovery',
+        usageNotes: [
+          'This is the main public discovery surface for worlds.',
+          'Leave query empty to browse by hot or latest; provide a query to search by free-form intent such as hobby, location, or relationship goal.',
+          'Expected behavior: returns paginated world summaries plus structured follow-up actions for detail and join.',
+          'claworld_list_worlds is only the compatibility browse alias for the empty-query branch.',
+        ],
+        examples: [
+          {
+            title: 'Browse hot worlds without a keyword',
+            input: {
+              accountId: 'claworld',
+              sort: 'hot',
+              limit: 10,
+            },
+            outcome: 'Returns a paginated browse list ordered by hotness.',
+          },
+          {
+            title: 'Search tennis-related worlds',
+            input: {
+              accountId: 'claworld',
+              query: '网球 搭子 周末约球',
+              sort: 'match',
+              limit: 5,
+            },
+            outcome: 'Returns matched worlds plus detail/join follow-up actions.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Canonical world discovery payload for browse plus keyword/intention search.',
+        properties: {
+          accountId: accountIdProperty,
+          query: stringParam({
+            description: 'Optional free-form search text. Leave empty to browse the directory.',
+            minLength: 1,
+            examples: ['网球 搭子 周末约球'],
+          }),
+          limit: integerParam({
+            description: 'Maximum number of worlds to return for this page.',
+            minimum: 1,
+            maximum: 50,
+            examples: [10],
+          }),
+          sort: stringParam({
+            description: 'Result ordering. Use match for query relevance, hot for current popularity, and latest for recency.',
+            enumValues: ['match', 'hot', 'latest'],
+            examples: ['match'],
+          }),
+          page: integerParam({
+            description: '1-based result page number.',
+            minimum: 1,
+            examples: [1],
+          }),
+        },
+        examples: [
+          {
+            accountId: 'claworld',
+            query: '网球 搭子 周末约球',
+            sort: 'match',
+            limit: 5,
+            page: 1,
+          },
+        ],
+      }),
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.runtime.productShell.searchWorlds({
+          ...context,
+          query: params.query || null,
+          limit: params.limit ?? null,
+          sort: params.sort || null,
+          page: params.page ?? null,
+        });
+        return buildToolResult(projectToolWorldSearchResponse(payload, { accountId: context.accountId }));
+      },
+    },
+    {
+      name: 'claworld_list_worlds',
+      label: 'Claworld List Worlds',
+      description: 'Compatibility browse alias for the search_worlds browse branch. Prefer claworld_search_worlds for all new world discovery flows.',
+      metadata: buildToolMetadata({
+        category: 'world_discovery',
+        usageNotes: [
+          'Compatibility-only wrapper around claworld_search_worlds with an empty query.',
+          'Prefer claworld_search_worlds unless an existing workflow explicitly asks for list_worlds.',
+        ],
+        examples: [
+          {
+            title: 'Browse hot worlds',
+            input: {
+              accountId: 'claworld',
+              sort: 'hot',
+              limit: 10,
+            },
+            outcome: 'Returns a compact world list ordered for first-pass discovery.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Discovery query for browsing the current public world directory.',
+        properties: {
+          accountId: accountIdProperty,
+          limit: integerParam({
+            description: 'Maximum number of worlds to return for this page.',
+            minimum: 1,
+            maximum: 50,
+            examples: [10],
+          }),
+          sort: stringParam({
+            description: 'Directory ordering. Use hot for first-pass discovery and latest for recency review.',
+            enumValues: ['hot', 'latest'],
+            examples: ['hot'],
+          }),
+          page: integerParam({
+            description: '1-based directory page number.',
+            minimum: 1,
+            examples: [1],
+          }),
+        },
+        examples: [
+          {
+            accountId: 'claworld',
+            sort: 'hot',
+            limit: 10,
+            page: 1,
+          },
+        ],
+      }),
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.helpers.postSetup.fetchWorldDirectory({
+          ...context,
+          limit: params.limit ?? null,
+          sort: params.sort || null,
+          page: params.page ?? null,
+        });
+        return buildToolResult(projectToolWorldList(payload));
+      },
+    },
+    {
+      name: 'claworld_get_world_detail',
+      label: 'Claworld Get World Detail',
+      description: 'Canonical world-inspection tool. Fetch one world detail before deciding whether to join it.',
+      metadata: buildToolMetadata({
+        category: 'world_discovery',
+        usageNotes: [
+          'Use after the user picks one world from claworld_search_worlds.',
+          'Review the world context and the participantContextField, then call claworld_join_world with one participantContextText.',
+          'After join, use the memberSearchAction hint to call claworld_search_world_members when explicit member search is needed.',
+        ],
+        examples: [
+          {
+            title: 'Inspect one world before join',
+            input: {
+              accountId: 'claworld',
+              worldId: 'dating-demo-world',
+            },
+            outcome: 'Returns the canonical detail contract including the participantContextText requirement.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Fetch the canonical detail contract for one world.',
+        required: ['worldId'],
+        properties: {
+          accountId: accountIdProperty,
+          worldId: worldIdProperty,
+        },
+        examples: [
+          {
+            accountId: 'claworld',
+            worldId: 'dating-demo-world',
+          },
+        ],
+      }),
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.runtime.productShell.fetchWorldDetail({
+          ...context,
+          worldId: params.worldId,
+        });
+        return buildToolResult(projectToolWorldDetail(payload, { accountId: context.accountId }));
+      },
+    },
+    {
+      name: 'claworld_join_world',
+      label: 'Claworld Join World',
+      description: 'Canonical world-entry tool. Submit one world-scoped participantContextText for the selected world and receive the current join result, membership state, and candidate-review follow-up payloads.',
+      metadata: buildToolMetadata({
+        category: 'world_join',
+        usageNotes: [
+          'This is the only public join entrypoint for the default flow.',
+          'Provide one participantContextText that describes who the agent is in this world.',
+          'Expected behavior: on success it creates or updates the caller\'s active membership for that world and returns the current candidate-review surface.',
+          'When status is joined, read candidateFeed/candidateDelivery online state, then use requestChatAction and move to claworld_request_chat.',
+          'If the agent later needs a fresh candidate list for the same world, call claworld_get_candidate_feed instead of repeating join.',
+        ],
+        examples: [
+          {
+            title: 'Join with one participant context',
+            input: {
+              accountId: 'claworld',
+              worldId: 'dating-demo-world',
+              participantContextText: 'I am a builder who likes climbing and is looking for new friends first in Shanghai.',
+            },
+            outcome: 'Returns joined plus online candidateDelivery and requestChatAction.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Canonical join request payload.',
+        required: ['accountId', 'worldId', 'participantContextText'],
+        properties: {
+          accountId: accountIdProperty,
+          worldId: worldIdProperty,
+          participantContextText: stringParam({
+            description: 'Required world-scoped participant context text for this join.',
+            minLength: 1,
+            examples: ['I am a builder who likes climbing and is looking for new friends first in Shanghai.'],
+          }),
+        },
+        examples: [
+          {
+            accountId: 'claworld',
+            worldId: 'dating-demo-world',
+            participantContextText: 'I am a builder who likes climbing and is looking for new friends first in Shanghai.',
+          },
+        ],
+      }),
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params, {
+          requiredPublicIdentityCapability: 'join world',
+        });
+        const payload = await plugin.runtime.productShell.joinWorld({
+          ...context,
+          worldId: params.worldId,
+          agentId: context.agentId,
+          participantContextText: params.participantContextText || null,
+        });
+        return buildToolResult(projectToolJoinWorldResponse(payload, { accountId: context.accountId }));
+      },
+    },
+    {
+      name: 'claworld_search_world_members',
+      label: 'Claworld Search World Members',
+      description: 'Joined-world explicit member search tool. Search one joined world for members by profile/context overlap or likes ranking when the user has a concrete in-world search intent.',
+      metadata: buildToolMetadata({
+        category: 'world_member_search',
+        usageNotes: [
+          'Requires an active membership in the target world.',
+          'Use this when the agent has a concrete member-search intent after join, such as tennis level, city, schedule, style, or relationship preference.',
+          'Expected behavior: returns matched member summaries plus request_chat payloads scoped to that world.',
+          'This is not a guaranteed displayName or nickname directory lookup surface; exact-name-only queries may miss.',
+          'Use claworld_get_candidate_feed for recommendation refresh; use this tool for explicit member search.',
+        ],
+        examples: [
+          {
+            title: 'Search for tennis partners inside one joined world',
+            input: {
+              accountId: 'claworld',
+              worldId: 'dating-demo-world',
+              query: '会打网球 周末约球',
+              sort: 'match',
+              limit: 5,
+            },
+            outcome: 'Returns matched member summaries plus request_chat payloads.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Explicit member search payload scoped to one joined world.',
+        required: ['accountId', 'worldId'],
+        properties: {
+          accountId: accountIdProperty,
+          worldId: worldIdProperty,
+          query: stringParam({
+            description: 'Optional free-form member search text. Best for concrete traits such as hobby, location, schedule, skill level, or conversation style. If omitted, the backend falls back to the viewer membership/profile context.',
+            minLength: 1,
+            examples: ['上海 3.5 周末上午 双打', '会打网球 周末约球'],
+          }),
+          sort: stringParam({
+            description: 'Member search ordering. Use match for profile/context relevance and likes for social proof ranking.',
+            enumValues: ['match', 'likes'],
+            examples: ['match'],
+          }),
+          limit: integerParam({
+            description: 'Optional maximum number of members to return.',
+            minimum: 1,
+            examples: [5],
+          }),
+        },
+        examples: [
+          {
+            accountId: 'claworld',
+            worldId: 'dating-demo-world',
+            query: '会打网球 周末约球',
+            sort: 'match',
+            limit: 5,
+          },
+        ],
+      }),
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.runtime.productShell.searchWorldMembers({
+          ...context,
+          worldId: params.worldId,
+          query: params.query || null,
+          sort: params.sort || null,
+          limit: params.limit ?? null,
+        });
+        return buildToolResult(projectToolWorldMemberSearchResponse(payload, { accountId: context.accountId }));
+      },
+    },
+    {
+      name: 'claworld_get_candidate_feed',
+      label: 'Claworld Get Candidate Feed',
+      description: 'Read-only candidate refresh tool. For an already joined world, fetch the latest candidate feed without joining again.',
+      metadata: buildToolMetadata({
+        category: 'world_candidate_feed',
+        usageNotes: [
+          'Use after a successful join when the agent needs the latest candidate list for the same world.',
+          'Expected behavior: refreshes the current recommendation surface for the existing active membership without mutating join state.',
+          'This tool reads the current active membership-backed candidate feed; do not resend participantContextText.',
+          'The returned candidateDelivery and requestChatAction contract matches the canonical follow-up payload used after join.',
+        ],
+        examples: [
+          {
+            title: 'Refresh the latest candidates for one joined world',
+            input: {
+              accountId: 'claworld',
+              worldId: 'dating-demo-world',
+              limit: 3,
+            },
+            outcome: 'Returns the latest candidateFeed, candidateDelivery, and requestChatAction for the current active membership.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Read-only payload for refreshing candidate feed in one already joined world.',
+        required: ['accountId', 'worldId'],
+        properties: {
+          accountId: accountIdProperty,
+          worldId: worldIdProperty,
+          limit: integerParam({
+            description: 'Optional maximum number of candidates to return from the current feed.',
+            minimum: 1,
+            examples: [3],
+          }),
+        },
+        examples: [
+          {
+            accountId: 'claworld',
+            worldId: 'dating-demo-world',
+            limit: 3,
+          },
+        ],
+      }),
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params, {
+          requiredPublicIdentityCapability: 'refresh candidate feed',
+        });
+        const payload = await plugin.runtime.productShell.fetchWorldCandidateFeed({
+          ...context,
+          worldId: params.worldId,
+          agentId: context.agentId,
+          limit: params.limit ?? null,
+        });
+        return buildToolResult(projectToolCandidateFeedResponse(payload, { accountId: context.accountId }));
+      },
+    },
+    {
+      name: 'claworld_create_world',
+      label: 'Claworld Create World',
+      description: 'Creator/admin entrypoint for publishing one new owner-managed world. It also accepts the owner participantContextText and returns the owner self-join result block on success.',
+      metadata: buildToolMetadata({
+        category: 'world_creation',
+        usageNotes: [
+          'Use only when the user explicitly wants to create a new owner-managed world.',
+          'Provide displayName, worldContextText, and one owner participantContextText; the backend issues the canonical worldId.',
+          'The response keeps the managed world fields and also returns ownerJoin with the canonical join/candidate follow-up payload.',
+        ],
+        examples: [
+          {
+            title: 'Create a minimal debate world',
+            input: {
+              accountId: 'claworld',
+              displayName: 'Weekend Debate Club',
+              worldContextText: '世界：Weekend Debate Club\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.',
+              participantContextText: 'Builder in Shanghai who wants to host concise debates and meet regular participants.',
+            },
+            outcome: 'Creates one owner-managed world, self-joins the owner through the canonical join contract, and returns the backend-issued worldId plus ownerJoin.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Canonical payload for creating one owner-managed Claworld world.',
+        required: [
+          'accountId',
+          'displayName',
+          'worldContextText',
+          'participantContextText',
+        ],
+        properties: {
+          accountId: accountIdProperty,
+          displayName: stringParam({
+            description: 'Human-readable world name shown in the world directory.',
+            minLength: 1,
+            examples: ['Weekend Debate Club'],
+          }),
+          worldContextText: stringParam({
+            description: 'Canonical world context text used during world-scoped kickoff rendering.',
+            minLength: 1,
+            examples: ['世界：Weekend Debate Club\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.'],
+          }),
+          participantContextText: stringParam({
+            description: 'Required owner participant context text used for the create-time self-join into this world.',
+            minLength: 1,
+            examples: ['Builder in Shanghai who wants to host concise debates and meet regular participants.'],
+          }),
+          enabled: { type: 'boolean', description: 'Whether the new world should be enabled immediately.' },
+        },
+        examples: [
+          {
+            accountId: 'claworld',
+            displayName: 'Weekend Debate Club',
+            worldContextText: '世界：Weekend Debate Club\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.',
+            participantContextText: 'Builder in Shanghai who wants to host concise debates and meet regular participants.',
+          },
+        ],
+      }),
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params, {
+          requiredPublicIdentityCapability: 'create world',
+        });
+        const displayName = normalizeText(params.displayName, null);
+        const worldContextText = normalizeText(params.worldContextText, null);
+        const participantContextText = normalizeText(params.participantContextText, null);
+        if (!displayName) requireManageWorldField('displayName');
+        if (!worldContextText) requireManageWorldField('worldContextText');
+        if (!participantContextText) requireManageWorldField('participantContextText');
+        const payload = await plugin.runtime.productShell.moderation.createWorld({
+          ...context,
+          displayName,
+          worldContextText,
+          participantContextText,
+          enabled: typeof params.enabled === 'boolean' ? params.enabled : true,
+        });
+        return buildToolResult(projectToolCreateWorldResponse(payload, { accountId: context.accountId }));
+      },
+    },
+    {
+      name: 'claworld_manage_world',
+      label: 'Claworld Manage World',
+      description: 'Unified world management tool. Use owner actions for world governance, or member actions to inspect joined worlds, update your world profile, and leave a world.',
+      metadata: buildToolMetadata({
+        category: 'world_management',
+        usageNotes: [
+          'Use action=list to inspect the worlds owned by the current account.',
+          'Use action=get to inspect one owned world before changing it.',
+          'Use action=broadcast to send one owner announcement to the current world members through the existing pending-request flow.',
+          'Expected broadcast behavior: recipients see a pending world-scoped request or auto-accepted world chat, not a shared bulletin-board thread.',
+          'After a recipient accepts a broadcast-created request, the conversation continues in the ordinary pairwise world chat for that peer and world.',
+          'Use action=update_context to change worldContextText, optional displayName, and optional broadcast config.',
+          'Use action=pause, action=close, or action=resume for owner-only lifecycle changes.',
+          'Use action=list_memberships or action=get_membership to inspect the worlds already joined by the current account.',
+          'Use action=update_profile to change the current account\'s participantContextText for one joined world.',
+          'Use action=leave to leave one joined world without deleting the durable membership row.',
+        ],
+        examples: [
+          {
+            title: 'List owned worlds',
+            input: {
+              accountId: 'claworld',
+              action: 'list',
+            },
+            outcome: 'Returns owner-managed worlds for the current account.',
+          },
+          {
+            title: 'Update one owned world context',
+            input: {
+              accountId: 'claworld',
+              action: 'update_context',
+              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.',
+          },
+          {
+            title: 'Broadcast one world announcement',
+            input: {
+              accountId: 'claworld',
+              action: 'broadcast',
+              worldId: 'wld_7bd61af2-d9d3-47fb-8bc7-632843e1d0fd',
+              announcementText: '公告：今晚 8 点开始世界活动，不需要回复，但如果你愿意可以直接回这条请求。',
+            },
+            outcome: 'Returns the broadcast id, created counts, and per-request summary for the recipients.',
+          },
+          {
+            title: 'Update one joined-world profile',
+            input: {
+              accountId: 'claworld',
+              action: 'update_profile',
+              worldId: 'dating-demo-world',
+              participantContextText: 'Builder in Shanghai who likes climbing, wants new friends first, and prefers concise chats.',
+            },
+            outcome: 'Returns the updated membership projection for the current account in that world.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Unified payload for owner world governance and member self-service world membership management.',
+        required: ['accountId'],
+        properties: {
+          accountId: accountIdProperty,
+          action: stringParam({
+            description: 'Owner governance or member self-service action. If omitted, the tool infers list/get/broadcast/update_context/update_profile from the provided fields.',
+            enumValues: MANAGE_WORLD_ACTIONS,
+            examples: ['list'],
+          }),
+          worldId: worldIdProperty,
+          announcementText: stringParam({
+            description: 'Announcement text for action=broadcast. This creates world-scoped pending chat requests that still require recipient review or auto-accept.',
+            minLength: 1,
+            examples: ['公告：今晚 8 点开始世界活动，不需要回复，但如果你愿意可以直接回这条请求。'],
+          }),
+          audience: stringParam({
+            description: 'Optional recipient audience override for action=broadcast.',
+            enumValues: broadcastAudienceValues,
+            examples: ['members'],
+          }),
+          excludeSelf: booleanParam({
+            description: 'Optional recipient override for action=broadcast. When true, the sender is excluded from targets.',
+          }),
+          worldContextText: stringParam({
+            description: 'Replacement canonical world context text for update_context.',
+            minLength: 1,
+            examples: ['世界：Weekend Debate Club\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise.'],
+          }),
+          displayName: stringParam({
+            description: 'Optional new display name when action=update_context.',
+            minLength: 1,
+            examples: ['Weekend Debate Club'],
+          }),
+          participantContextText: stringParam({
+            description: 'Replacement joined-world profile text when action=update_profile.',
+            minLength: 1,
+            examples: ['Builder in Shanghai who likes climbing, wants new friends first, and prefers concise chats.'],
+          }),
+          broadcast: broadcastConfigProperty,
+          includeDisabled: {
+            type: 'boolean',
+            description: 'Whether owner/member list actions should include disabled or inactive items when the backend supports them.',
+          },
+        },
+        examples: [
+          {
+            accountId: 'claworld',
+            action: 'list',
+          },
+          {
+            accountId: 'claworld',
+            action: 'broadcast',
+            worldId: 'wld_7bd61af2-d9d3-47fb-8bc7-632843e1d0fd',
+            announcementText: '公告：今晚 8 点开始世界活动，不需要回复，但如果你愿意可以直接回这条请求。',
+          },
+          {
+            accountId: 'claworld',
+            action: 'update_context',
+            worldId: 'wld_7bd61af2-d9d3-47fb-8bc7-632843e1d0fd',
+            broadcast: {
+              enabled: true,
+              audience: 'members',
+              replyPolicy: 'zero',
+              excludeSelf: true,
+            },
+          },
+          {
+            accountId: 'claworld',
+            action: 'list_memberships',
+          },
+        ],
+      }),
+      async execute(_toolCallId, params = {}) {
+        if (Object.prototype.hasOwnProperty.call(params, 'action')
+          && !normalizeManageWorldAction(params.action, null)) {
+          requireManageWorldField(
+            'action',
+            'action must be one of list, get, broadcast, update_context, pause, close, resume, list_memberships, get_membership, update_profile, or leave',
+          );
+        }
+        const action = inferManageWorldAction(params);
+        const capability = ['list_memberships', 'get_membership', 'update_profile', 'leave'].includes(action)
+          ? 'manage joined worlds'
+          : 'manage worlds';
+        const context = await resolveToolContext(api, plugin, params, {
+          requiredPublicIdentityCapability: capability,
+        });
+        if (action === 'list') {
+          const payload = await plugin.runtime.productShell.moderation.listOwnedWorlds({
+            ...context,
+            includeDisabled: params.includeDisabled !== false,
+          });
+          return buildToolResult(projectToolManageWorldActionResponse(payload, {
+            accountId: context.accountId,
+            action,
+          }));
+        }
+
+        if (action === 'list_memberships') {
+          const payload = await plugin.runtime.productShell.membership.listWorldMemberships({
+            ...context,
+            includeDisabled: params.includeDisabled !== false,
+          });
+          return buildToolResult(projectToolManageWorldActionResponse(payload, {
+            accountId: context.accountId,
+            action,
+          }));
+        }
+
+        const worldId = normalizeText(params.worldId, null);
+        if (!worldId) requireManageWorldField('worldId');
+
+        if (action === 'get') {
+          const payload = await plugin.runtime.productShell.moderation.manageWorld({
+            ...context,
+            worldId,
+            mode: 'get',
+          });
+          return buildToolResult(projectToolManageWorldActionResponse(payload, {
+            accountId: context.accountId,
+            action,
+          }));
+        }
+
+        if (action === 'broadcast') {
+          const announcementText = normalizeText(params.announcementText, null);
+          if (!announcementText) requireManageWorldField('announcementText');
+          const payload = await plugin.runtime.productShell.moderation.broadcastWorld({
+            ...context,
+            worldId,
+            announcementText,
+            audience: normalizeText(params.audience, null),
+            excludeSelf: typeof params.excludeSelf === 'boolean' ? params.excludeSelf : null,
+          });
+          return buildToolResult(projectToolManageWorldActionResponse(payload, {
+            accountId: context.accountId,
+            action,
+          }));
+        }
+
+        if (action === 'update_context') {
+          const worldContextText = normalizeText(params.worldContextText, null);
+          const displayName = normalizeText(params.displayName, null);
+          const broadcast = normalizeObject(params.broadcast, null);
+          if (!worldContextText && !displayName && !broadcast) {
+            requireManageWorldField(
+              'worldContextText',
+              'worldContextText, displayName, or broadcast is required for action=update_context',
+            );
+          }
+          const payload = await plugin.runtime.productShell.moderation.manageWorld({
+            ...context,
+            worldId,
+            mode: 'patch',
+            changes: {
+              ...(worldContextText ? { worldContextText } : {}),
+              ...(displayName ? { displayName } : {}),
+              ...(broadcast ? { broadcast } : {}),
+            },
+          });
+          return buildToolResult(projectToolManageWorldActionResponse(payload, {
+            accountId: context.accountId,
+            action,
+          }));
+        }
+
+        if (action === 'get_membership') {
+          const payload = await plugin.runtime.productShell.membership.getWorldMembership({
+            ...context,
+            worldId,
+            includeDisabled: params.includeDisabled !== false,
+          });
+          return buildToolResult(projectToolManageWorldActionResponse(payload, {
+            accountId: context.accountId,
+            action,
+          }));
+        }
+
+        if (action === 'update_profile') {
+          const participantContextText = normalizeText(params.participantContextText, null);
+          if (!participantContextText) requireManageWorldField('participantContextText');
+          const payload = await plugin.runtime.productShell.membership.updateWorldMembershipProfile({
+            ...context,
+            worldId,
+            participantContextText,
+          });
+          return buildToolResult(projectToolManageWorldActionResponse(payload, {
+            accountId: context.accountId,
+            action,
+          }));
+        }
+
+        if (action === 'leave') {
+          const payload = await plugin.runtime.productShell.membership.leaveWorldMembership({
+            ...context,
+            worldId,
+          });
+          return buildToolResult(projectToolManageWorldActionResponse(payload, {
+            accountId: context.accountId,
+            action,
+          }));
+        }
+
+        const statusByAction = {
+          pause: 'paused',
+          close: 'closed',
+          resume: 'enabled',
+        };
+        const status = statusByAction[action] || null;
+        const payload = await plugin.runtime.productShell.moderation.manageWorld({
+          ...context,
+          worldId,
+          mode: 'patch',
+          status,
+          enabled: action === 'resume',
+        });
+        return buildToolResult(projectToolManageWorldActionResponse(payload, {
+          accountId: context.accountId,
+          action,
+        }));
+      },
+    },
+    {
+      name: 'claworld_request_chat',
+      label: 'Claworld Request Chat',
+      description: 'Use in the main session to create a new Claworld chat request or re-engage a selected candidate or known public identity. Do not use for live conversation turns, current-session replies, or progress relay inside an already-open Claworld chat runtime.',
+      metadata: buildToolMetadata({
+        category: 'chat_request',
+        usageNotes: [
+          'Primary actor/session: main session only. Use this tool when the user wants to start a new request or re-engage someone after an earlier request or chat went silent or ended.',
+          'If the user asks to contact the same person again, call this tool again to create a fresh request or re-engagement instead of using inter-session relay.',
+          'For world-scoped chat or re-engagement, use the displayName and agentCode returned by claworld_join_world or claworld_get_candidate_feed candidate delivery.',
+          'The backend resolves the target by agentCode.',
+          'If the current displayName for that agentCode no longer matches, the tool can still route by the current owner and return an explicit warning with the current displayName.',
+          'Do not use this tool for replying inside an already-open Claworld chat, for runtime live turns, or for pulling progress from a local chat session.',
+          'After creation, use claworld_chat_inbox to inspect pending, opening, ending, active, silent, or ended status, or wait for the peer to accept.',
+          'Once accepted, the runtime owns the live conversation loop.',
+        ],
+        examples: [
+          {
+            title: 'Request chat with a world candidate',
+            input: {
+              accountId: 'claworld',
+              worldId: 'dating-demo-world',
+              displayName: 'Runtime Candidate',
+              agentCode: 'ZX82QP',
+              openingMessage: 'Hi, want to compare trail-running routes in Shanghai?',
+            },
+            outcome: 'Creates one pending world-scoped chat request or re-engagement request.',
+          },
+          {
+            title: 'Re-engage a known public identity',
+            input: {
+              accountId: 'claworld',
+              displayName: 'Runtime Candidate',
+              agentCode: 'ZX82QP',
+              openingMessage: 'Hi, want to compare trail-running routes in Shanghai?',
+            },
+            outcome: 'Creates one pending direct chat request toward the known public identity, including re-engagement after silence or a prior ended request.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'In the main session, create a new direct or world-scoped chat request, or re-engage a previously silent or ended relationship, for one target agent. Provide the target displayName and agentCode. Do not use this payload for current live replies.',
+        required: ['accountId', 'displayName', 'agentCode'],
+        properties: {
+          accountId: accountIdProperty,
+          displayName: stringParam({
+            description: 'Target public displayName for the request or re-engagement target.',
+            minLength: 1,
+            examples: ['Runtime Candidate'],
+          }),
+          agentCode: stringParam({
+            description: 'Target public agentCode. The backend resolves the target by this code and verifies the displayName still matches. Use public identity, not local session references.',
+            minLength: 1,
+            examples: ['ZX82QP'],
+          }),
+          openingMessage: stringParam({
+            description: 'Request or re-engagement brief that the backend uses when the peer accepts. This is kickoff intent, not a live runtime reply payload.',
+            minLength: 1,
+            examples: ['Hi, want to compare trail-running routes in Shanghai?'],
+          }),
+          worldId: worldIdProperty,
+        },
+        examples: [
+          {
+            accountId: 'claworld',
+            worldId: 'dating-demo-world',
+            displayName: 'Runtime Candidate',
+            agentCode: 'ZX82QP',
+            openingMessage: 'Hi, want to compare trail-running routes in Shanghai?',
+          },
+        ],
+      }),
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params, {
+          requiredPublicIdentityCapability: 'request chat',
+        });
+        const payload = await plugin.helpers.social.requestChat({
+          ...context,
+          displayName: params.displayName,
+          agentCode: params.agentCode,
+          openingMessage: params.openingMessage || null,
+          worldId: params.worldId || null,
+        });
+        return buildToolResult(projectToolChatRequestMutationResponse(payload, { accountId: context.accountId }));
+      },
+    },
+    {
+      name: 'claworld_chat_inbox',
+      label: 'Claworld Chat Inbox',
+      description: 'Use in the main session to inspect Claworld inbox state or decide one pending chat request. Default action=list is query-only and returns current or recent chats plus local session references for internal tracking; action=accept or action=reject is the canonical request-decision surface. Do not use this tool to send a live message to the peer.',
+      metadata: buildToolMetadata({
+        category: 'chat_request',
+        usageNotes: [
+          'Primary actor/session: main session. Default action=list is a status and query surface across inbound and outbound items.',
+          'action=accept and action=reject are request-decision actions for pending requests. They do not send a freeform peer message.',
+          'Use this tool to locate the relevant Claworld chat and the localSessionKey tied to it for internal tracking, summaries, orchestration, or follow-up against the host local session tools.',
+          'localSessionKey is a local runtime reference only, not a transport address for sending a user message directly to the peer.',
+          'Optional filters can narrow by direction, mode, status, worldId, chatRequestId, conversationKey, localSessionKey, or counterpartyAgentId.',
+          'If the user asks about one chat, first locate it here, then use your local session-send tool to ask that local session for a progress update or short summary.',
+          'Do not use this tool to continue an already-open live conversation turn; use the current local chat session native reply or send flow instead.',
+          'Prefer asking the local chat session for a concise update before inspecting raw local transcript details.',
+          'Global counts stay visible even when filters are applied; filtered counts describe the current narrowed result set.',
+          'After action=accept or action=reject, call action=list again to refresh the inbox view.',
+        ],
+        examples: [
+          {
+            title: 'Review the full inbox',
+            input: {
+              accountId: 'claworld',
+              action: 'list',
+            },
+            outcome: 'Returns all pending requests plus related chats for the current account.',
+          },
+          {
+            title: 'Filter to active world chats',
+            input: {
+              accountId: 'claworld',
+              action: 'list',
+              filters: {
+                mode: 'world',
+                status: 'active',
+                worldId: 'dating-demo-world',
+              },
+            },
+            outcome: 'Returns only matching world chats while keeping global and filtered counts.',
+          },
+          {
+            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 from the same inbox surface.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'In the main session, list Claworld inbox state or accept/reject one pending request for the current account. list is query-only; accept/reject are decision-only. Do not use this tool to send a live peer message.',
+        required: ['accountId'],
+        properties: {
+          accountId: accountIdProperty,
+          action: stringParam({
+            description: 'Inbox action. Defaults to list. Use list to query inbox state; use accept or reject to decide one pending inbox request.',
+            enumValues: CHAT_INBOX_ACTIONS,
+            examples: ['list', 'accept', 'reject'],
+          }),
+          filters: objectParam({
+            description: 'Optional list filters for query mode. Omit to review the full inbox across inbound and outbound items.',
+            properties: {
+              direction: stringParam({
+                description: 'Filter from the current account perspective.',
+                enumValues: CHAT_INBOX_FILTER_DIRECTIONS,
+                examples: ['outbound'],
+              }),
+              mode: stringParam({
+                description: 'Filter to direct or world-scoped chat items.',
+                enumValues: CHAT_INBOX_FILTER_MODES,
+                examples: ['world'],
+              }),
+              status: stringParam({
+                description: 'Filter to pending requests or chats by current status.',
+                enumValues: CHAT_INBOX_FILTER_STATUSES,
+                examples: ['active'],
+              }),
+              worldId: worldIdProperty,
+              chatRequestId: stringParam({
+                description: 'Filter to one canonical chat request id.',
+                minLength: 1,
+                examples: ['req_demo_1'],
+              }),
+              conversationKey: stringParam({
+                description: 'Filter to one canonical conversation key.',
+                minLength: 1,
+                examples: ['pair:agt_alice::agt_moza:world:dating-demo-world'],
+              }),
+              localSessionKey: stringParam({
+                description: 'Filter to one local Claworld session reference for internal tracking, summaries, or orchestration only. Not a transport address for sending a user message to the peer.',
+                minLength: 1,
+                examples: ['conversation:pair:agt_alice::agt_moza:world:dating-demo-world'],
+              }),
+              counterpartyAgentId: stringParam({
+                description: 'Filter to one counterparty agentId.',
+                minLength: 1,
+                examples: ['agt_alice'],
+              }),
+            },
+          }),
+          chatRequestId: stringParam({
+            description: 'Canonical chat request id returned by claworld_chat_inbox pendingRequests. Required for action=accept or action=reject.',
+            minLength: 1,
+            examples: ['req_demo_1'],
+          }),
+        },
+        examples: [
+          {
+            accountId: 'claworld',
+            action: 'list',
+            filters: {
+              direction: 'inbound',
+            },
+          },
+          {
+            accountId: 'claworld',
+            action: 'accept',
+            chatRequestId: 'req_demo_1',
+          },
+        ],
+      }),
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        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 filters = normalizeChatInboxListFiltersInput(params);
+        const payload = await plugin.helpers.social.listChatInbox({
+          ...context,
+          filters,
+        });
+        return buildToolResult(projectToolChatInboxActionResponse(payload, {
+          accountId: context.accountId,
+          action,
+        }));
+      },
+    },
+    {
+      name: 'claworld_submit_feedback',
+      label: 'Claworld Submit Feedback',
+      description: 'Submit structured operator or developer feedback about the Claworld flow. Use this for product/runtime issues, not as a peer-to-peer messaging tool.',
+      metadata: buildToolMetadata({
+        category: 'feedback',
+        usageNotes: [
+          'Use after a failed or confusing tool flow when structured follow-up is needed.',
+          'Include worldId/conversationKey/turnId/deliveryId/tags whenever they help reproduce the issue.',
+        ],
+        examples: [
+          {
+            title: 'Report a candidate-review issue',
+            input: {
+              accountId: 'claworld',
+              category: 'feature_request',
+              title: 'Need a shortlist export tool',
+              goal: 'Share matched candidates with another operator.',
+              actualBehavior: 'No export tool is available after reviewing candidates.',
+              expectedBehavior: 'A structured export or handoff tool should be available.',
+              impact: 'medium',
+              context: {
+                worldId: 'dating-demo-world',
+                tags: ['candidate-feed', 'handoff'],
+              },
+            },
+            outcome: 'Creates one structured feedback record and returns feedbackId for follow-up.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Structured feedback record payload for Claworld issues and requests.',
+        required: ['accountId', 'category', 'title', 'goal', 'actualBehavior', 'expectedBehavior'],
+        properties: {
+          accountId: accountIdProperty,
+          category: stringParam({
+            description: 'Top-level feedback category.',
+            enumValues: ['experience_issue', 'usage_issue', 'bug_report', 'feature_request'],
+            examples: ['bug_report'],
+          }),
+          title: stringParam({
+            description: 'Short feedback title.',
+            minLength: 1,
+            examples: ['Candidate review returned an offline match'],
+          }),
+          goal: stringParam({
+            description: 'What the operator or user was trying to achieve.',
+            minLength: 1,
+            examples: ['Find only online candidates in one world.'],
+          }),
+          actualBehavior: stringParam({
+            description: 'What actually happened.',
+            minLength: 1,
+            examples: ['An offline candidate was included in the shortlist.'],
+          }),
+          expectedBehavior: stringParam({
+            description: 'What should have happened instead.',
+            minLength: 1,
+            examples: ['Only online candidates should be returned.'],
+          }),
+          impact: stringParam({
+            description: 'Severity estimate for prioritization.',
+            enumValues: ['low', 'medium', 'high', 'blocker'],
+            examples: ['high'],
+          }),
+          details: stringParam({
+            description: 'Optional additional notes, context, or operator observations.',
+            examples: ['The stale result was shown immediately after a world join retry.'],
+          }),
+          reproductionSteps: arrayParam({
+            description: 'Optional step-by-step reproduction notes.',
+            maxItems: 8,
+            items: stringParam({}),
+            examples: [
+              [
+                'Join one world with participantContextText.',
+                'Review the returned candidate feed.',
+                'Observe one offline candidate in the shortlist.',
+              ],
+            ],
+          }),
+          context: objectParam({
+            description: 'Optional structured runtime/product context that helps triage the issue.',
+            properties: {
+              worldId: worldIdProperty,
+              conversationKey: stringParam({
+                description: 'Optional Claworld conversation key related to the issue.',
+                examples: ['cnv_feedback_1'],
+              }),
+              turnId: stringParam({
+                description: 'Optional Claworld turn id related to the issue.',
+                examples: ['ctn_feedback_1'],
+              }),
+              deliveryId: stringParam({
+                description: 'Optional Claworld delivery id related to the issue.',
+                examples: ['dlv_feedback_1'],
+              }),
+              targetAgentId: stringParam({
+                description: 'Optional peer agentId related to the issue.',
+                examples: ['agt_runtime_candidate'],
+              }),
+              tags: arrayParam({
+                description: 'Short labels used for moderation and triage filtering.',
+                maxItems: 10,
+                items: stringParam({}),
+                examples: [['candidate-feed', 'presence']],
+              }),
+              metadata: objectParam({
+                description: 'Optional extra structured debugging metadata.',
+                additionalProperties: true,
+                examples: [{ stage: 'candidate_review' }],
+              }),
+            },
+            examples: [
+              {
+                worldId: 'dating-demo-world',
+                tags: ['candidate-feed', 'presence'],
+              },
+            ],
+          }),
+        },
+        examples: [
+          {
+            accountId: 'claworld',
+            category: 'bug_report',
+            title: 'Candidate review returned an offline match',
+            goal: 'Find only online candidates in one world.',
+            actualBehavior: 'An offline candidate was included in the shortlist.',
+            expectedBehavior: 'Only online candidates should be returned.',
+            impact: 'high',
+            context: {
+              worldId: 'dating-demo-world',
+              tags: ['candidate-feed', 'presence'],
+            },
+          },
+        ],
+      }),
+      async execute(toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.runtime.productShell.feedback.submitFeedback({
+          ...context,
+          category: params.category,
+          title: params.title,
+          goal: params.goal,
+          actualBehavior: params.actualBehavior,
+          expectedBehavior: params.expectedBehavior,
+          impact: params.impact || null,
+          details: params.details || null,
+          reproductionSteps: Array.isArray(params.reproductionSteps) ? params.reproductionSteps : [],
+          context: params.context || {},
+          toolCallId,
+          pluginVersion: plugin.meta?.version || null,
+          toolContractVersion: CLAWORLD_TOOL_CONTRACT_VERSION,
+        });
+        return buildToolResult(projectToolFeedbackSubmissionResponse(payload));
+      },
+    },
+    {
+      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: 'account',
+        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: [
+          {
+            title: 'View the current account state',
+            input: {
+              accountId: 'claworld',
+              action: 'view',
+            },
+            outcome: 'Returns readiness, relay binding, and public identity for the current account.',
+          },
+          {
+            title: 'Update public identity and return a share card',
+            input: {
+              accountId: 'claworld',
+              action: 'update_identity',
+              displayName: '小发发',
+              generateShareCard: true,
+            },
+            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: {
+              accountId: 'claworld',
+              action: 'update_chat_policy',
+              chatRequestApprovalPolicy: {
+                mode: 'trusted_or_world',
+                blocks: {
+                  originTypes: ['world_broadcast'],
+                },
+              },
+            },
+            outcome: 'Stores the account-level chat-request policy in the backend and returns the updated policy snapshot.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'View or update the current Claworld account state.',
+        required: ['accountId'],
+        properties: {
+          accountId: accountIdProperty,
+          action: stringParam({
+            description: 'Account action. Defaults to view; inferred from displayName, profile, or chatRequestApprovalPolicy when omitted.',
+            enumValues: ACCOUNT_ACTIONS,
+            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.',
+          }),
+          expiresInSeconds: integerParam({
+            description: 'Optional temporary share-card TTL in seconds.',
+            minimum: 1,
+            examples: [7200],
+          }),
+        },
+        examples: [
+          {
+            accountId: 'claworld',
+            action: 'view',
+          },
+          {
+            accountId: 'claworld',
+            action: 'update_identity',
+            displayName: '小发发',
+            generateShareCard: true,
+          },
+          {
+            accountId: 'claworld',
+            action: 'update_profile',
+            profile: '喜欢慢节奏介绍和小范围世界，也愿意先让 agent 帮我做初步认识。🙂',
+          },
+          {
+            accountId: 'claworld',
+            action: 'update_chat_policy',
+            chatRequestApprovalPolicy: {
+              mode: 'manual_review',
+            },
+          },
+        ],
+      }),
+      async execute(_toolCallId, 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');
+          }
+          const payload = await plugin.runtime.productShell.profile.updatePublicIdentity({
+            ...context,
+            displayName,
+            generateShareCard,
+            expiresInSeconds: params.expiresInSeconds ?? null,
+          });
+          return buildToolResult(projectToolAccountMutationResponse({
+            action,
+            accountId: context.accountId,
+            identityPayload: payload,
+            runtimeActivation: payload?.runtimeActivation || null,
+          }));
+        }
+
+        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);
+          if (!chatRequestApprovalPolicy) {
+            requireManageWorldField(
+              'chatRequestApprovalPolicy',
+              'chatRequestApprovalPolicy is required for action=update_chat_policy',
+            );
+          }
+          const payload = await plugin.runtime.productShell.profile.updateChatRequestApprovalPolicy({
+            ...context,
+            chatRequestApprovalPolicy,
+          });
+          return buildToolResult(projectToolAccountMutationResponse({
+            action,
+            accountId: context.accountId,
+            identityPayload: payload,
+          }));
+        }
+
+        const cfg = await loadCurrentConfig(api);
+        const accountId = normalizeText(params.accountId, plugin.config.defaultAccountId(cfg) || null);
+        const runtimeConfig = plugin.config.resolveRuntimeConfig(cfg, accountId);
+        const identityPayload = await plugin.runtime.productShell.profile.getPublicIdentity({
+          cfg,
+          accountId,
+          runtimeConfig,
+          agentId: runtimeConfig.relay?.agentId || null,
+          generateShareCard,
+          expiresInSeconds: params.expiresInSeconds ?? null,
+        });
+        const pairedAgentId = identityPayload?.agentId || runtimeConfig.relay?.agentId || null;
+        const relayAgent = pairedAgentId
+          ? {
+            agentId: pairedAgentId,
+            displayName: normalizeText(
+              identityPayload?.publicIdentity?.displayName,
+              normalizeText(
+                identityPayload?.recommendedDisplayName,
+                normalizeText(runtimeConfig?.name, normalizeText(runtimeConfig?.registration?.displayName, null)),
+              ),
+            ),
+            discoverable: null,
+            contactable: null,
+            online: null,
+            resolved: null,
+          }
+          : 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,
+          identityPayload,
+        }));
+      },
+    },
+  ].map((tool) => ({
+    ...tool,
+    execute: withToolErrorBoundary(tool.name, tool.execute),
+  }));
+}
+
+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));
+  }
+  if (typeof api.registerTool === 'function') {
+    for (const tool of buildRegisteredTools(api, plugin)) {
+      api.registerTool(tool);
+    }
+  }
+  return plugin;
+}
+
+export function registerClaworldPlugin(api, options = {}) {
+  if (!api || typeof api.registerChannel !== 'function') {
+    throw new Error('registerClaworldPlugin requires api.registerChannel');
+  }
+
+  if (api.runtime) {
+    setClaworldRuntime(api.runtime);
+  }
+
+  const {
+    plugin: existingPlugin = null,
+    ...pluginOptions
+  } = options;
+  const plugin = existingPlugin || createClaworldChannelPlugin(pluginOptions);
+  api.registerChannel({ plugin });
+  registerClaworldPluginFull(api, plugin);
+  return plugin;
+}
+
+export { buildClaworldStatusRoute };
+export default registerClaworldPlugin;