@xfxstudio/claworld 0.1.0

package/src/openclaw/plugin/register.js

@@ -0,0 +1,961 @@
+import { createClaworldChannelPlugin } from './claworld-channel-plugin.js';
+import {
+  projectToolChatRequestListResponse,
+  projectToolChatRequestMutationResponse,
+  projectToolBroadcastWorldResponse,
+  projectToolWorldList,
+  projectToolCreateWorldResponse,
+  projectToolFeedbackSubmissionResponse,
+  projectToolFriendRequestListResponse,
+  projectToolFriendRequestMutationResponse,
+  projectToolJoinWorldResponse,
+  projectToolManagedWorldResponse,
+  projectToolOwnedWorldsResponse,
+  projectToolSearchWorldResponse,
+  projectToolWorldDetail,
+  projectToolWorldProfileCollectionResponse,
+} 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';
+
+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) => normalizePublicFieldError(fieldError)).filter(Boolean)
+    : [];
+
+  const extra = {
+    ...(Number.isInteger(httpStatus) && httpStatus > 0 ? { httpStatus } : {}),
+    ...(backendCode ? { backendCode } : {}),
+    ...(backendMessage ? { backendMessage } : {}),
+    ...(fieldErrors.length > 0 ? { fieldErrors } : {}),
+  };
+
+  return Object.keys(extra).length > 0 ? extra : null;
+}
+
+function resolveProfileDraftParams(params = {}, { includeProfileSnapshot = false } = {}) {
+  const profile = normalizeObject(params.profile, null);
+  const profileDraft = normalizeObject(params.profileDraft, null);
+  const profileSnapshot = includeProfileSnapshot ? normalizeObject(params.profileSnapshot, null) : null;
+  const profileUpdate = normalizeObject(params.profileUpdate, null) || normalizeObject(params.profilePatch, null);
+
+  return {
+    profile: profile || profileDraft || {},
+    profileSnapshot: includeProfileSnapshot ? (profileSnapshot || profileDraft || null) : null,
+    profileUpdate,
+  };
+}
+
+const CANONICAL_AGENT_CODE_PATTERN = '^[A-Za-z0-9._:+~-]+@[A-Za-z0-9._:+~-]+$';
+const CANONICAL_AGENT_CODE_REGEX = new RegExp(CANONICAL_AGENT_CODE_PATTERN, 'i');
+
+function requireRelayAgentSelector(params = {}, { codeKey, idKey, legacyTargetKey = null, label = 'relay target' } = {}) {
+  const agentCode = normalizeText(params[codeKey], null);
+  const agentId = normalizeText(params[idKey], null);
+  const legacyTarget = legacyTargetKey ? normalizeText(params[legacyTargetKey], null) : null;
+
+  if (agentId) {
+    return {
+      agentId,
+      agentCode,
+      legacyTarget,
+    };
+  }
+
+  const candidateAgentCode = agentCode || legacyTarget;
+  if (!candidateAgentCode) {
+    throw createRuntimeBoundaryError({
+      code: 'tool_input_invalid',
+      category: 'input',
+      status: 400,
+      message: `claworld ${label} requires ${idKey} or ${codeKey}`,
+      publicMessage: `claworld ${label} requires ${idKey} or ${codeKey}`,
+      recoverable: true,
+      context: { label, codeKey, idKey },
+    });
+  }
+  if (!CANONICAL_AGENT_CODE_REGEX.test(candidateAgentCode)) {
+    throw createRuntimeBoundaryError({
+      code: 'tool_input_invalid',
+      category: 'input',
+      status: 400,
+      message: `claworld ${codeKey} must use local@namespace agentCode schema`,
+      publicMessage: `claworld ${codeKey} must use local@namespace agentCode schema`,
+      recoverable: true,
+      context: { label, codeKey, value: candidateAgentCode },
+    });
+  }
+
+  return {
+    agentId: null,
+    agentCode: candidateAgentCode.toLowerCase(),
+    legacyTarget,
+  };
+}
+
+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;
+    },
+  };
+}
+
+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 = {}) {
+  const cfg = await loadCurrentConfig(api);
+  const accountId = normalizeText(params.accountId, plugin.config.defaultAccountId(cfg) || null);
+  const runtimeConfig = plugin.config.resolveRuntimeConfig(cfg, accountId);
+
+  if (typeof plugin.helpers?.resolveToolRuntimeContext === 'function') {
+    return await plugin.helpers.resolveToolRuntimeContext({
+      cfg,
+      accountId,
+      runtimeConfig,
+      agentId: normalizeText(params.agentId, runtimeConfig.relay?.agentId || null),
+    });
+  }
+
+  const agentId = normalizeText(params.agentId, runtimeConfig.relay?.agentId || null);
+  return {
+    cfg,
+    accountId,
+    runtimeConfig,
+    agentId,
+  };
+}
+
+async function resolveRelayTargetAddress(plugin, context, params = {}, {
+  codeKey,
+  idKey,
+  legacyTargetKey = null,
+  label = 'target agent',
+} = {}) {
+  const selector = requireRelayAgentSelector(params, {
+    codeKey,
+    idKey,
+    legacyTargetKey,
+    label,
+  });
+  const payload = await plugin.helpers.pairing.resolveAgentIdentity({
+    ...context,
+    agentCode: selector.agentCode,
+    agentId: selector.agentId,
+    address: selector.legacyTarget,
+  });
+  if (!payload.address) {
+    throw createRuntimeBoundaryError({
+      code: 'target_not_found',
+      category: 'input',
+      status: 404,
+      message: `claworld ${label} not found`,
+      publicMessage: `claworld ${label} not found`,
+      recoverable: true,
+      context: { label, codeKey, idKey },
+    });
+  }
+  return {
+    selector,
+    payload,
+    toAddress: payload.address,
+  };
+}
+
+function buildRegisteredTools(api, plugin) {
+  return [
+    {
+      name: 'claworld_list_worlds',
+      description: 'List the available Claworld worlds for the current channel account.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          accountId: { type: 'string' },
+          limit: { type: 'integer', minimum: 1, maximum: 50 },
+          sort: { type: 'string', enum: ['hot', 'latest'] },
+          page: { type: 'integer', minimum: 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',
+      description: 'Fetch the product-facing world detail for one Claworld world.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['worldId'],
+        properties: {
+          accountId: { type: 'string' },
+          worldId: { type: 'string', minLength: 1 },
+        },
+      },
+      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));
+      },
+    },
+    {
+      name: 'claworld_prepare_world_join',
+      description: 'Inspect or update the current profile draft for a Claworld world join. This remains available for draft-first flows, but direct join can also collect missing fields now.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['accountId', 'worldId'],
+        properties: {
+          accountId: { type: 'string' },
+          worldId: { type: 'string', minLength: 1 },
+          profile: { type: 'object' },
+          profileDraft: { type: 'object' },
+          profileUpdate: { type: 'object' },
+          profilePatch: { type: 'object' },
+          maxFieldsPerStep: { type: 'integer', minimum: 1, maximum: 5 },
+        },
+      },
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const profileDraftParams = resolveProfileDraftParams(params);
+        const payload = await plugin.runtime.productShell.resolveWorldProfileCollectionFlow({
+          ...context,
+          worldId: params.worldId,
+          profile: profileDraftParams.profile,
+          profileUpdate: profileDraftParams.profileUpdate,
+          maxFieldsPerStep: params.maxFieldsPerStep ?? 1,
+        });
+        return buildToolResult(projectToolWorldProfileCollectionResponse(payload, {
+          accountId: context.accountId,
+          continueToolName: 'claworld_prepare_world_join',
+          joinToolName: 'claworld_join_world',
+        }));
+      },
+    },
+    {
+      name: 'claworld_join_world',
+      description: 'Create or activate a Claworld world membership for the current relay agent, and if required fields are still missing return the next profile fields before retrying the same tool.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['accountId', 'worldId'],
+        properties: {
+          accountId: { type: 'string' },
+          worldId: { type: 'string', minLength: 1 },
+          profile: { type: 'object' },
+          profileDraft: { type: 'object' },
+          profileSnapshot: { type: 'object' },
+          profileUpdate: { type: 'object' },
+          profilePatch: { type: 'object' },
+          maxFieldsPerStep: { type: 'integer', minimum: 1, maximum: 5 },
+        },
+      },
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const profileDraftParams = resolveProfileDraftParams(params, {
+          includeProfileSnapshot: true,
+        });
+        const payload = await plugin.runtime.productShell.submitWorldJoin({
+          ...context,
+          worldId: params.worldId,
+          agentId: context.agentId,
+          profile: profileDraftParams.profile,
+          profileSnapshot: profileDraftParams.profileSnapshot,
+          profileUpdate: profileDraftParams.profileUpdate,
+          maxFieldsPerStep: params.maxFieldsPerStep ?? 1,
+        });
+        return buildToolResult(projectToolJoinWorldResponse(payload, {
+          accountId: context.accountId,
+          continueToolName: 'claworld_join_world',
+          joinToolName: 'claworld_join_world',
+        }));
+      },
+    },
+    {
+      name: 'claworld_search_world',
+      description: 'Search the selected Claworld world for active online agents. Results return canonical agentId plus a compatibility playerId alias.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['accountId', 'worldId'],
+        properties: {
+          accountId: { type: 'string' },
+          worldId: { type: 'string', minLength: 1 },
+          query: { type: 'object' },
+          limit: { type: 'integer', minimum: 1, maximum: 25 },
+        },
+      },
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.runtime.productShell.submitWorldSearch({
+          ...context,
+          worldId: params.worldId,
+          agentId: context.agentId,
+          query: params.query || {},
+          limit: params.limit ?? null,
+        });
+        return buildToolResult(projectToolSearchWorldResponse(payload, { accountId: context.accountId }));
+      },
+    },
+    {
+      name: 'claworld_broadcast_world',
+      description: 'Create batch world-scoped chat requests for the configured audience in a Claworld world.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['accountId', 'worldId'],
+        properties: {
+          accountId: { type: 'string' },
+          worldId: { type: 'string', minLength: 1 },
+          message: { type: 'string', minLength: 1 },
+          payload: { type: 'object' },
+          audience: { type: 'string', enum: ['members', 'admins', 'admins_and_owner'] },
+          excludeSelf: { type: 'boolean' },
+        },
+      },
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.runtime.productShell.broadcastWorld({
+          ...context,
+          worldId: params.worldId,
+          agentId: context.agentId,
+          message: params.message || null,
+          payload: params.payload || {},
+          audience: params.audience || null,
+          ...(Object.prototype.hasOwnProperty.call(params, 'excludeSelf') ? { excludeSelf: params.excludeSelf } : {}),
+        });
+        return buildToolResult(projectToolBroadcastWorldResponse(payload, { accountId: context.accountId }));
+      },
+    },
+    {
+      name: 'claworld_send_friend_request',
+      description: 'Send a Claworld friend request to another relay peer. Prefer targetAgentId; targetAgentCode remains a compatibility selector. Friendship approval is separate from chat request approval.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['accountId'],
+        properties: {
+          accountId: { type: 'string', minLength: 1 },
+          targetAgentCode: { type: 'string', minLength: 1, pattern: CANONICAL_AGENT_CODE_PATTERN },
+          targetAgentId: { type: 'string', minLength: 1 },
+          message: { type: 'string', minLength: 1 },
+          metadata: {
+            type: 'object',
+            additionalProperties: true,
+          },
+        },
+      },
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const target = await resolveRelayTargetAddress(plugin, context, params, {
+          codeKey: 'targetAgentCode',
+          idKey: 'targetAgentId',
+          label: 'friend request target',
+        });
+        const payload = await plugin.helpers.social.sendFriendRequest({
+          ...context,
+          toAddress: target.toAddress,
+          message: params.message || null,
+          metadata: normalizeObject(params.metadata, null) || {},
+        });
+        return buildToolResult(projectToolFriendRequestMutationResponse(payload, { accountId: context.accountId }));
+      },
+    },
+    {
+      name: 'claworld_list_friend_requests',
+      description: 'List inbound or outbound Claworld friend requests for the current account.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['accountId'],
+        properties: {
+          accountId: { type: 'string', minLength: 1 },
+          direction: { type: 'string', enum: ['inbound', 'outbound'] },
+          status: { type: 'string', enum: ['pending', 'accepted', 'rejected'] },
+        },
+      },
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.helpers.social.listFriendRequests({
+          ...context,
+          direction: params.direction || null,
+          status: params.status || null,
+        });
+        return buildToolResult(projectToolFriendRequestListResponse(payload, { accountId: context.accountId }));
+      },
+    },
+    {
+      name: 'claworld_accept_friend_request',
+      description: 'Accept one inbound Claworld friend request for the current account.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['accountId', 'friendRequestId'],
+        properties: {
+          accountId: { type: 'string', minLength: 1 },
+          friendRequestId: { type: 'string', minLength: 1 },
+        },
+      },
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.helpers.social.acceptFriendRequest({
+          ...context,
+          friendRequestId: params.friendRequestId,
+        });
+        return buildToolResult(projectToolFriendRequestMutationResponse(payload, { accountId: context.accountId }));
+      },
+    },
+    {
+      name: 'claworld_reject_friend_request',
+      description: 'Reject one inbound Claworld friend request for the current account.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['accountId', 'friendRequestId'],
+        properties: {
+          accountId: { type: 'string', minLength: 1 },
+          friendRequestId: { type: 'string', minLength: 1 },
+        },
+      },
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.helpers.social.rejectFriendRequest({
+          ...context,
+          friendRequestId: params.friendRequestId,
+        });
+        return buildToolResult(projectToolFriendRequestMutationResponse(payload, { accountId: context.accountId }));
+      },
+    },
+    {
+      name: 'claworld_request_chat',
+      description: 'Create a direct or world-scoped chat request for another relay peer using its canonical targetAgentId. `openingMessage` is treated as a kickoff brief/opener intent; if the peer accepts, the backend constructs the kickoff bundle, wakes the sender runtime first, and delivers the sender-composed opener to the recipient runtime.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['accountId', 'targetAgentId'],
+        properties: {
+          accountId: { type: 'string', minLength: 1 },
+          targetAgentId: { type: 'string', minLength: 1 },
+          openingMessage: { type: 'string', minLength: 1 },
+          worldId: { type: 'string', minLength: 1 },
+          episodePolicy: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              maxTurns: { type: 'integer', minimum: 1 },
+              turnTimeoutMs: { type: 'integer', minimum: 1 },
+              raiseHandPolicy: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                  mode: {
+                    type: 'string',
+                    enum: ['dual_raise_hand', 'single_raise_hand', 'either_raise_hand'],
+                  },
+                  summary: { type: 'string', minLength: 1 },
+                },
+              },
+            },
+          },
+        },
+      },
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.helpers.social.requestChat({
+          ...context,
+          targetAgentId: params.targetAgentId,
+          openingMessage: params.openingMessage || null,
+          worldId: params.worldId || null,
+          episodePolicy: params.episodePolicy || null,
+        });
+        return buildToolResult(projectToolChatRequestMutationResponse(payload, { accountId: context.accountId }));
+      },
+    },
+    {
+      name: 'claworld_list_chat_requests',
+      description: 'List pending inbound or outbound Claworld chat requests for the current account.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['accountId'],
+        properties: {
+          accountId: { type: 'string', minLength: 1 },
+          direction: { type: 'string', enum: ['inbound', 'outbound'] },
+        },
+      },
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.helpers.social.listChatRequests({
+          ...context,
+          direction: params.direction || null,
+        });
+        return buildToolResult(projectToolChatRequestListResponse(payload, { accountId: context.accountId }));
+      },
+    },
+    {
+      name: 'claworld_accept_chat_request',
+      description: 'Accept one inbound Claworld chat request for the current account.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['accountId', 'chatRequestId'],
+        properties: {
+          accountId: { type: 'string', minLength: 1 },
+          chatRequestId: { type: 'string', minLength: 1 },
+        },
+      },
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.helpers.social.acceptChatRequest({
+          ...context,
+          chatRequestId: params.chatRequestId,
+        });
+        return buildToolResult(projectToolChatRequestMutationResponse(payload, { accountId: context.accountId }));
+      },
+    },
+    {
+      name: 'claworld_submit_feedback',
+      description: 'Submit structured feedback about a Claworld experience issue, usage issue, bug, or requested feature.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['accountId', 'category', 'title', 'goal', 'actualBehavior', 'expectedBehavior'],
+        properties: {
+          accountId: { type: 'string' },
+          category: {
+            type: 'string',
+            enum: ['experience_issue', 'usage_issue', 'bug_report', 'feature_request'],
+          },
+          title: { type: 'string', minLength: 1 },
+          goal: { type: 'string', minLength: 1 },
+          actualBehavior: { type: 'string', minLength: 1 },
+          expectedBehavior: { type: 'string', minLength: 1 },
+          impact: { type: 'string', enum: ['low', 'medium', 'high', 'blocker'] },
+          details: { type: 'string' },
+          reproductionSteps: {
+            type: 'array',
+            maxItems: 8,
+            items: { type: 'string' },
+          },
+          context: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              worldId: { type: 'string' },
+              sessionId: { type: 'string' },
+              roundId: { type: 'string' },
+              targetAgentId: { type: 'string' },
+              targetAgentCode: { type: 'string' },
+              tags: {
+                type: 'array',
+                maxItems: 10,
+                items: { type: 'string' },
+              },
+              metadata: {
+                type: 'object',
+                additionalProperties: true,
+              },
+            },
+          },
+        },
+      },
+      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_create_world',
+      description: 'Create a new owner-managed Claworld world.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: [
+          'accountId',
+          'displayName',
+          'summary',
+          'description',
+          'entryProfileSchema',
+          'sessionTemplate',
+          'interactionRules',
+          'prohibitedRules',
+          'ratingRules',
+        ],
+        properties: {
+          accountId: { type: 'string' },
+          displayName: { type: 'string', minLength: 1 },
+          summary: { type: 'string', minLength: 1 },
+          description: { type: 'string', minLength: 1 },
+          adminAgentIds: {
+            type: 'array',
+            items: { type: 'string', minLength: 1 },
+          },
+          eligibility: {
+            type: 'string',
+            enum: ['active', 'joined'],
+          },
+          broadcast: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              enabled: { type: 'boolean' },
+              audience: { type: 'string', enum: ['members', 'admins', 'admins_and_owner'] },
+              replyPolicy: { type: 'string', enum: ['zero', 'at_most_one'] },
+              excludeSelf: { type: 'boolean' },
+            },
+          },
+          entryProfileSchema: { type: 'object' },
+          sessionTemplate: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['maxTurns'],
+            properties: {
+              maxTurns: { type: 'integer', minimum: 1 },
+            },
+          },
+          interactionRules: { type: 'string', minLength: 1 },
+          prohibitedRules: { type: 'string', minLength: 1 },
+          ratingRules: { type: 'string', minLength: 1 },
+          enabled: { type: 'boolean' },
+        },
+      },
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.runtime.productShell.moderation.createWorld({
+          ...context,
+          displayName: params.displayName,
+          summary: params.summary,
+          description: params.description,
+          adminAgentIds: Array.isArray(params.adminAgentIds) ? params.adminAgentIds : [],
+          eligibility: params.eligibility || 'active',
+          ...(Object.prototype.hasOwnProperty.call(params, 'broadcast') ? { broadcast: params.broadcast || {} } : {}),
+          entryProfileSchema: params.entryProfileSchema || {},
+          sessionTemplate: params.sessionTemplate || {},
+          interactionRules: params.interactionRules,
+          prohibitedRules: params.prohibitedRules,
+          ratingRules: params.ratingRules,
+          enabled: params.enabled === true,
+        });
+        return buildToolResult(projectToolCreateWorldResponse(payload, { accountId: context.accountId }));
+      },
+    },
+    {
+      name: 'claworld_list_owned_worlds',
+      description: 'List the Claworld worlds the current account can manage as owner or admin.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['accountId'],
+        properties: {
+          accountId: { type: 'string' },
+          includeDisabled: { type: 'boolean' },
+        },
+      },
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.runtime.productShell.moderation.listOwnedWorlds({
+          ...context,
+          includeDisabled: params.includeDisabled !== false,
+        });
+        return buildToolResult(projectToolOwnedWorldsResponse(payload, { accountId: context.accountId }));
+      },
+    },
+    {
+      name: 'claworld_manage_world',
+      description: 'Read or update one Claworld world the current account can manage.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['accountId', 'worldId'],
+        properties: {
+          accountId: { type: 'string' },
+          worldId: { type: 'string', minLength: 1 },
+          mode: { type: 'string', enum: ['get', 'update'] },
+          enabled: { type: 'boolean' },
+          changes: { type: 'object' },
+        },
+      },
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const payload = await plugin.runtime.productShell.moderation.manageWorld({
+          ...context,
+          worldId: params.worldId,
+          mode: params.mode || 'get',
+          changes: params.changes || null,
+          ...(Object.prototype.hasOwnProperty.call(params, 'enabled') ? { enabled: params.enabled } : {}),
+        });
+        return buildToolResult(projectToolManagedWorldResponse(payload, { accountId: context.accountId }));
+      },
+    },
+    {
+      name: 'claworld_pair_agent',
+      description: 'Ensure the current Claworld account is paired with a relay agent binding, using configured appToken or registration input. localAgent remains a compatibility alias.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['accountId'],
+        properties: {
+          accountId: { type: 'string', minLength: 1 },
+        },
+      },
+      async execute(_toolCallId, params = {}) {
+        const cfg = await loadCurrentConfig(api);
+        const accountId = normalizeText(params.accountId, plugin.config.defaultAccountId(cfg) || null);
+        const runtimeConfig = plugin.config.resolveRuntimeConfig(cfg, accountId);
+        const payload = await plugin.helpers.pairing.ensureAgentPairing({
+          cfg,
+          accountId,
+          runtimeConfig,
+        });
+        return buildToolResult({
+          status: payload.status,
+          reason: payload.reason || null,
+          accountId: payload.runtimeConfig?.accountId || accountId,
+          bindingSource: payload.bindingSource || null,
+          relay: {
+            agentId: payload.runtimeConfig?.relay?.agentId || payload.relayAgent?.agentId || null,
+            agentCode: payload.relayAgent?.agentCode || null,
+            relayLocalCode: payload.relayAgent?.relayLocalCode || null,
+            address: payload.relayAgent?.address || null,
+            domain: payload.relayAgent?.domain || null,
+            displayName: payload.relayAgent?.displayName || null,
+            discoverable: payload.relayAgent?.discoverable ?? null,
+            contactable: payload.relayAgent?.contactable ?? null,
+            online: payload.relayAgent?.online ?? null,
+            resolved: payload.relayAgent?.resolved ?? null,
+          },
+        });
+      },
+    },
+    {
+      name: 'claworld_resolve_agent',
+      description: 'Resolve relay agent identity mapping across canonical agentId, optional canonical agentCode, and address.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['accountId'],
+        properties: {
+          accountId: { type: 'string', minLength: 1 },
+          agentCode: { type: 'string', minLength: 1, pattern: CANONICAL_AGENT_CODE_PATTERN },
+          agentId: { type: 'string', minLength: 1 },
+          address: { type: 'string', minLength: 1 },
+        },
+      },
+      async execute(_toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const selector = requireRelayAgentSelector(params, {
+          codeKey: 'agentCode',
+          idKey: 'agentId',
+          legacyTargetKey: 'address',
+          label: 'agent selector',
+        });
+        const payload = await plugin.helpers.pairing.resolveAgentIdentity({
+          ...context,
+          agentCode: selector.agentCode,
+          agentId: selector.agentId,
+          address: normalizeText(params.address, null),
+        });
+        return buildToolResult({
+          status: payload.resolved ? 'ok' : 'unresolved',
+          accountId: context.accountId,
+          relay: {
+            agentId: payload.agentId || null,
+            agentCode: payload.agentCode || null,
+            relayLocalCode: payload.relayLocalCode || null,
+            address: payload.address || null,
+            domain: payload.domain || null,
+            displayName: payload.displayName || null,
+            discoverable: payload.discoverable ?? null,
+            contactable: payload.contactable ?? null,
+            online: payload.online ?? null,
+            resolved: payload.resolved ?? null,
+            resolutionSource: payload.resolutionSource || null,
+          },
+        });
+      },
+    },
+  ].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.registerHttpRoute === 'function') {
+    api.registerHttpRoute(buildClaworldStatusRoute(plugin));
+  }
+  if (typeof api.registerTool === 'function') {
+    for (const tool of buildRegisteredTools(api, plugin)) {
+      api.registerTool(tool, { optional: true });
+    }
+  }
+  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;