@xfxstudio/claworld 0.1.0

package/src/openclaw/plugin/claworld-channel-plugin.js

@@ -0,0 +1,3118 @@
+import {
+  applyRuntimeIdentity,
+  buildRuntimeAuthHeaders,
+  normalizeRuntimeRegistration,
+  resolveRuntimeAppToken,
+} from './account-identity.js';
+import {
+  claworldChannelConfigJsonSchema,
+  claworldChannelConfigSchema,
+  defaultClaworldAccountId,
+  inspectClaworldChannelAccount,
+  listClaworldAccountIds,
+  resolveClaworldChannelAccount,
+  resolveClaworldRuntimeConfig,
+  validateClaworldChannelConfig,
+} from './config-schema.js';
+import {
+  claworldOnboardingAdapter,
+  claworldSetupAdapter,
+} from './onboarding.js';
+import { createClaworldLifecycleManager } from './lifecycle.js';
+import { createClaworldRelayClient } from './relay-client.js';
+import { createRelayEventProtocol } from '../protocol/relay-event-protocol.js';
+import { createInboundSessionRouter } from '../runtime/inbound-session-router.js';
+import { createOutboundSessionBridge } from '../runtime/outbound-session-bridge.js';
+import { createCanonicalResultBuilder } from '../runtime/canonical-result-builder.js';
+import { createDemoSessionBootstrap } from '../runtime/demo-session-bootstrap.js';
+import {
+  createModeratedWorld,
+  fetchOwnedWorlds,
+  manageModeratedWorld,
+} from '../runtime/world-moderation-helper.js';
+import { submitFeedbackReport } from '../runtime/feedback-helper.js';
+import {
+  buildWorldSelectionPrompt,
+  buildCandidateDeliverySummary,
+  buildPostSetupWorldDirectory,
+  buildRequiredFieldExplanation,
+  broadcastWorld,
+  fetchWorldSearch,
+  fetchWorldCandidateFeed,
+  fetchWorldJoinCheck,
+  fetchWorldDetail,
+  joinWorld,
+  submitWorldJoin,
+  submitWorldSearch,
+  resolveWorldJoinFlow,
+  resolveWorldSelection,
+  resolveWorldProfileCollectionFlow,
+  resolveWorldSelectionFlow,
+} from '../runtime/product-shell-helper.js';
+import { getClaworldRuntime } from './runtime.js';
+import {
+  createRuntimeBoundaryError,
+  normalizeRuntimeBoundaryError,
+  serializeRuntimeBoundaryError,
+} from '../../lib/runtime-errors.js';
+import {
+  ACCEPTED_CHAT_KICKOFF_PAYLOAD_KIND,
+  readAcceptedChatKickoffRuntimeContext,
+  resolveAcceptedChatKickoffViewer,
+} from '../../lib/accepted-chat-kickoff.js';
+
+function normalizeRelayHttpBaseUrl(serverUrl) {
+  const parsed = new URL(serverUrl);
+  if (parsed.protocol === 'ws:') parsed.protocol = 'http:';
+  if (parsed.protocol === 'wss:') parsed.protocol = 'https:';
+  parsed.pathname = '';
+  parsed.search = '';
+  parsed.hash = '';
+  return parsed.toString().replace(/\/$/, '');
+}
+
+function inferRelayDomain(runtimeConfig = {}) {
+  const defaultToAddress = String(runtimeConfig.relay?.defaultToAddress || '').trim();
+  const atIndex = defaultToAddress.indexOf('@');
+  if (atIndex > 0 && atIndex < defaultToAddress.length - 1) {
+    return defaultToAddress.slice(atIndex + 1).trim().toLowerCase();
+  }
+  return 'relay.local';
+}
+
+const RELAY_LOCAL_AGENT_CODE_PATTERN = /^[A-Za-z0-9._:+~-]+$/;
+const RELAY_CANONICAL_AGENT_CODE_PATTERN = /^[A-Za-z0-9._:+~-]+@[A-Za-z0-9._:+~-]+$/;
+
+function normalizeRelayDomainName(value, fallback = null) {
+  const normalized = normalizeClaworldText(value, fallback)?.toLowerCase() || null;
+  if (!normalized) return fallback;
+  if (!/^[a-z0-9._:+~-]+$/.test(normalized)) return fallback;
+  return normalized;
+}
+
+function normalizeRelayLocalAgentCode(value, fallback = null) {
+  const normalized = normalizeClaworldText(value, fallback)?.toLowerCase() || null;
+  if (!normalized) return fallback;
+  if (!RELAY_LOCAL_AGENT_CODE_PATTERN.test(normalized)) return fallback;
+  return normalized;
+}
+
+function parseCanonicalRelayAgentCode(value) {
+  const normalized = normalizeClaworldText(value, null)?.toLowerCase() || null;
+  if (!normalized || !RELAY_CANONICAL_AGENT_CODE_PATTERN.test(normalized)) return null;
+  const atIndex = normalized.indexOf('@');
+  if (atIndex <= 0 || atIndex >= normalized.length - 1) return null;
+  const relayLocalCode = normalizeRelayLocalAgentCode(normalized.slice(0, atIndex), null);
+  const domain = normalizeRelayDomainName(normalized.slice(atIndex + 1), null);
+  if (!relayLocalCode || !domain) return null;
+  return {
+    agentCode: `${relayLocalCode}@${domain}`,
+    relayLocalCode,
+    domain,
+  };
+}
+
+function buildCanonicalRelayAgentCode(relayLocalCode, runtimeConfig = {}, domainOverride = null) {
+  const normalizedRelayLocalCode = normalizeRelayLocalAgentCode(relayLocalCode, null);
+  const domain = normalizeRelayDomainName(domainOverride, null)
+    || normalizeRelayDomainName(inferRelayDomain(runtimeConfig), null);
+  if (!normalizedRelayLocalCode || !domain) return null;
+  return `${normalizedRelayLocalCode}@${domain}`;
+}
+
+function normalizeCanonicalRelayAgentCode(value, runtimeConfig = {}) {
+  const parsed = parseCanonicalRelayAgentCode(value);
+  if (parsed) return parsed.agentCode;
+  const relayLocalCode = normalizeRelayLocalAgentCode(value, null);
+  if (!relayLocalCode) return null;
+  return buildCanonicalRelayAgentCode(relayLocalCode, runtimeConfig);
+}
+
+function normalizeRelayIdentityInput({ runtimeConfig = {}, agentId = null, agentCode = null, address = null } = {}) {
+  const normalizedAgentId = normalizeClaworldText(agentId, null);
+  const normalizedAddress = normalizeClaworldText(resolveRelayAddress(address || agentCode || '', runtimeConfig), null)?.toLowerCase() || null;
+  const parsedCanonicalAgentCode = parseCanonicalRelayAgentCode(agentCode)
+    || parseCanonicalRelayAgentCode(normalizedAddress);
+  const relayLocalCode = normalizeRelayLocalAgentCode(agentCode, null)
+    || parsedCanonicalAgentCode?.relayLocalCode
+    || null;
+  const domain = parsedCanonicalAgentCode?.domain
+    || normalizeRelayDomainName(normalizedAddress?.split('@')[1], null)
+    || normalizeRelayDomainName(inferRelayDomain(runtimeConfig), null);
+  const normalizedAgentCode = parsedCanonicalAgentCode?.agentCode
+    || (relayLocalCode ? buildCanonicalRelayAgentCode(relayLocalCode, runtimeConfig, domain) : null)
+    || null;
+
+  return {
+    agentId: normalizedAgentId,
+    agentCode: normalizedAgentCode,
+    relayLocalCode,
+    address: normalizedAddress || normalizedAgentCode || null,
+    domain,
+  };
+}
+
+function buildRelayAgentSummary(item = {}, runtimeConfig = {}) {
+  const normalizedAgentId = normalizeClaworldText(item?.agentId, null);
+  const relayLocalCode = normalizeRelayLocalAgentCode(item?.agentCode, null);
+  const address = normalizeClaworldText(item?.address, null)?.toLowerCase()
+    || buildCanonicalRelayAgentCode(relayLocalCode, runtimeConfig, item?.domain)
+    || null;
+  const parsedCanonicalAgentCode = parseCanonicalRelayAgentCode(address);
+  const domain = normalizeRelayDomainName(item?.domain, null)
+    || parsedCanonicalAgentCode?.domain
+    || normalizeRelayDomainName(inferRelayDomain(runtimeConfig), null);
+  const canonicalAgentCode = parsedCanonicalAgentCode?.agentCode
+    || buildCanonicalRelayAgentCode(relayLocalCode, runtimeConfig, domain)
+    || null;
+
+  return {
+    agentId: normalizedAgentId,
+    agentCode: canonicalAgentCode,
+    relayLocalCode: relayLocalCode || parsedCanonicalAgentCode?.relayLocalCode || null,
+    domain,
+    address: address || canonicalAgentCode || null,
+    displayName: normalizeClaworldText(item?.displayName, null),
+    discoverable: typeof item?.discoverable === 'boolean' ? item.discoverable : null,
+    contactable: typeof item?.contactable === 'boolean' ? item.contactable : null,
+    online: typeof item?.online === 'boolean' ? item.online : null,
+  };
+}
+
+function normalizeClaworldTarget(raw) {
+  if (typeof raw !== 'string') return undefined;
+  let value = raw.trim();
+  if (!value) return undefined;
+  value = value.replace(/^claworld:/i, '').replace(/^user:/i, '').replace(/^@/, '').trim();
+  return value || undefined;
+}
+
+function resolveRelayAddress(to, runtimeConfig = {}) {
+  const normalized = normalizeClaworldTarget(typeof to === 'string' ? to : '');
+  const fallback = normalizeClaworldTarget(runtimeConfig.relay?.defaultToAddress || '');
+  const candidate = normalized || fallback;
+  if (!candidate) return '';
+  if (candidate.includes('@')) return candidate.toLowerCase();
+  return `${candidate.toLowerCase()}@${inferRelayDomain(runtimeConfig)}`;
+}
+
+function normalizeClaworldText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function resolveNormalizedText(value, fallback = null) {
+  return normalizeClaworldText(value, fallback);
+}
+
+function normalizeClaworldInteger(value, fallback = null) {
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized)) return fallback;
+  return Math.trunc(normalized);
+}
+
+function shouldAuthorizeBridgedCommand({ runtimeConfig = {}, relayEvent, incomingText }) {
+  if (runtimeConfig.testing?.allowBridgedCommandDispatch !== true) {
+    return false;
+  }
+  if (relayEvent !== 'turn.deliver') {
+    return false;
+  }
+  return typeof incomingText === 'string' && incomingText.trim().startsWith('/');
+}
+
+const CLAWORLD_RAISE_HAND_DIRECTIVE = '[[CLAWORLD_RAISE_HAND]]';
+const CLAWORLD_RAISE_HAND_DIRECTIVE_PATTERN = /\[\[\s*CLAWORLD_RAISE_HAND\s*\]\]/gi;
+
+function extractControlledReply(text) {
+  let raiseHand = false;
+  const sanitized = String(text || '')
+    .replace(CLAWORLD_RAISE_HAND_DIRECTIVE_PATTERN, () => {
+      raiseHand = true;
+      return ' ';
+    })
+    .replace(/[ \t]+\n/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+
+  return {
+    text: sanitized || (raiseHand ? 'I am ready to conclude this round.' : ''),
+    control: raiseHand ? { type: 'raise_hand', raiseHand: true } : null,
+  };
+}
+
+const CLAWORLD_RELAY_OPERATIONAL_NOTICE_PATTERNS = [
+  /^🧭\s*New session:\s+\S+/i,
+  /^🧹\s*Auto-compaction complete(?:\s*\(count \d+\))?\.$/i,
+  /^↪️\s*Model Fallback:/i,
+  /^↪️\s*Model Fallback cleared:/i,
+];
+
+const CLAWORLD_RELAY_OPERATIONAL_SUFFIX_PATTERNS = [
+  /^Usage:\s+.+\s+in\s+\/\s+.+\s+out(?:\s+·\s+est\s+.+)?$/i,
+];
+
+const CLAWORLD_RUNTIME_OUTPUT_PREVIEW_LIMIT = 3;
+
+function stripRelayOperationalSuffix(text) {
+  const lines = String(text || '').split('\n');
+  while (lines.length > 0) {
+    const lastLine = String(lines[lines.length - 1] || '').trim();
+    if (!lastLine) {
+      lines.pop();
+      continue;
+    }
+    if (!CLAWORLD_RELAY_OPERATIONAL_SUFFIX_PATTERNS.some((pattern) => pattern.test(lastLine))) {
+      break;
+    }
+    lines.pop();
+  }
+  return lines.join('\n').trim();
+}
+
+function classifyRelayContinuationText(text) {
+  const normalized = stripRelayOperationalSuffix(text);
+  if (!normalized) {
+    return {
+      text: '',
+      operational: Boolean(String(text || '').trim()),
+    };
+  }
+  if (CLAWORLD_RELAY_OPERATIONAL_NOTICE_PATTERNS.some((pattern) => pattern.test(normalized))) {
+    return {
+      text: '',
+      operational: true,
+    };
+  }
+  return {
+    text: normalized,
+    operational: false,
+  };
+}
+
+function sanitizeRelayContinuationText(text) {
+  return classifyRelayContinuationText(text).text;
+}
+
+function previewRuntimeOutputText(text, maxLength = 120) {
+  const normalized = String(text || '').replace(/\s+/g, ' ').trim();
+  if (!normalized) return '';
+  if (normalized.length <= maxLength) return normalized;
+  return `${normalized.slice(0, Math.max(0, maxLength - 1)).trimEnd()}...`;
+}
+
+function appendRuntimeOutputPreview(previews, text) {
+  const preview = previewRuntimeOutputText(text);
+  if (!preview) return;
+  if (previews.includes(preview)) return;
+  if (previews.length >= CLAWORLD_RUNTIME_OUTPUT_PREVIEW_LIMIT) return;
+  previews.push(preview);
+}
+
+function buildRelayContinuationText({ finalTexts = [], blockTexts = [] } = {}) {
+  const sanitizedFinalTexts = finalTexts
+    .map((entry) => sanitizeRelayContinuationText(entry))
+    .filter(Boolean);
+  if (sanitizedFinalTexts.length > 0) {
+    return {
+      text: sanitizedFinalTexts.join('\n\n').trim(),
+      source: 'final',
+    };
+  }
+  const sanitizedBlockTexts = blockTexts
+    .map((entry) => sanitizeRelayContinuationText(entry))
+    .filter(Boolean);
+  if (sanitizedBlockTexts.length > 0) {
+    return {
+      text: sanitizedBlockTexts.join('\n').trim(),
+      source: 'block',
+    };
+  }
+  return {
+    text: '',
+    source: 'none',
+  };
+}
+
+function resolveContinuationState(turnData = {}) {
+  const continuation = turnData?.continuation;
+  if (!continuation || typeof continuation !== 'object' || Array.isArray(continuation)) {
+    return { allowed: true, reason: null, roundStatus: null };
+  }
+  return {
+    allowed: continuation.allowed !== false,
+    reason: normalizeClaworldText(continuation.reason, null),
+    roundStatus: normalizeClaworldText(continuation.roundStatus, null),
+  };
+}
+
+function resolveBackendGuidanceMessages(payload = {}) {
+  const guidance = payload?.guidance;
+  if (!guidance || typeof guidance !== 'object' || Array.isArray(guidance)) return [];
+  const messages = Array.isArray(guidance.messages) ? guidance.messages : [];
+  return messages
+    .map((message, index) => {
+      const text = normalizeClaworldText(message?.text, null);
+      if (!text) return null;
+      return {
+        text,
+        contextKey:
+          normalizeClaworldText(message?.contextKey, null)
+          || `claworld:backend-guidance:${normalizeClaworldText(message?.kind, 'message')}:${index}`,
+      };
+    })
+    .filter(Boolean);
+}
+
+function enqueueBackendGuidance({
+  runtime,
+  sessionKey,
+  payload,
+} = {}) {
+  if (!runtime?.system?.enqueueSystemEvent || !sessionKey) {
+    return { skipped: true, reason: 'missing_runtime_or_session', count: 0 };
+  }
+
+  const messages = resolveBackendGuidanceMessages(payload);
+  if (messages.length === 0) {
+    return { skipped: true, reason: 'no_backend_guidance', count: 0 };
+  }
+
+  for (const message of messages) {
+    runtime.system.enqueueSystemEvent(message.text, {
+      sessionKey,
+      contextKey: message.contextKey,
+    });
+  }
+
+  return {
+    skipped: false,
+    reason: null,
+    count: messages.length,
+  };
+}
+
+function buildClaworldDirectoryEntries(config = {}, accountId = null) {
+  const accountIds = listClaworldAccountIds(config);
+  const currentAccountId = String(accountId || '').trim();
+  const entries = [];
+
+  for (const id of accountIds) {
+    const account = inspectClaworldChannelAccount(config, id);
+    if (!account?.enabled || !account?.configured) continue;
+    const normalizedId = String(account.accountId || id || '').trim();
+    if (!normalizedId) continue;
+    if (currentAccountId && normalizedId === currentAccountId) continue;
+    entries.push({
+      id: resolveRelayAddress(normalizedId, account),
+      name: normalizedId,
+      handle: normalizedId,
+      rank: 100,
+    });
+  }
+
+  const current = inspectClaworldChannelAccount(config, currentAccountId || null);
+  const defaultTarget = resolveRelayAddress(current?.relay?.defaultToAddress || '', current || {});
+  if (defaultTarget) {
+    const localPart = defaultTarget.split('@')[0] || defaultTarget;
+    if (!entries.some((entry) => entry.id === defaultTarget)) {
+      entries.push({ id: defaultTarget, name: localPart, handle: localPart, rank: 50 });
+    }
+  }
+
+  return entries;
+}
+
+async function deliverRelayMessage({ runtimeConfig, to, text, fetchImpl, logger, outboundContext = {}, messagePayload = null }) {
+  const fromAgentId = runtimeConfig.relay?.agentId;
+  if (!fromAgentId) throw new Error('claworld relay.agentId is required for outbound send');
+
+  const toAddress = resolveRelayAddress(to, runtimeConfig);
+  if (!toAddress) throw new Error('claworld outbound target is required');
+
+  const normalizedText = normalizeClaworldText(text, null);
+  const payload = messagePayload && typeof messagePayload === 'object'
+    ? { ...messagePayload }
+    : {};
+
+  if (!normalizeClaworldText(payload.text, null) && normalizedText) {
+    payload.text = normalizedText;
+  }
+  if (!normalizeClaworldText(payload.text, null)) {
+    throw new Error('claworld outbound text is required');
+  }
+  payload.source = normalizeClaworldText(payload.source, 'openclaw-claworld');
+  payload.accountId = normalizeClaworldText(payload.accountId, runtimeConfig.accountId);
+
+  const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
+  const result = await fetchJson(fetchImpl, `${baseUrl}/v1/messages`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      ...(runtimeConfig.apiKey ? { 'x-api-key': runtimeConfig.apiKey } : {}),
+      ...buildRuntimeAuthHeaders(runtimeConfig),
+    },
+    body: JSON.stringify({
+      fromAgentId,
+      toAddress,
+      payload,
+      conversation: {
+        conversationKey: outboundContext.conversationKey || outboundContext.metadata?.conversationKey || null,
+        worldId: outboundContext.worldId || outboundContext.metadata?.worldId || null,
+        scope: outboundContext.scope || outboundContext.sessionScope || outboundContext.metadata?.scope || null,
+        conversationId: outboundContext.conversationId || outboundContext.metadata?.conversationId || null,
+        threadId: outboundContext.threadId || outboundContext.metadata?.threadId || null,
+        sessionKey: outboundContext.sessionKey || outboundContext.SessionKey || null,
+      },
+    }),
+  });
+
+  if (!result.ok) {
+    logger.error?.('[claworld:outbound] session request failed', { status: result.status, body: result.body });
+    throw createRuntimeBoundaryError({
+      code: 'relay_message_delivery_failed',
+      category: 'transport',
+      status: result.status >= 500 ? 502 : result.status,
+      message: `claworld outbound failed: ${result.status}`,
+      publicMessage: 'claworld outbound message delivery failed',
+      recoverable: true,
+      context: {
+        accountId: runtimeConfig.accountId || null,
+        fromAgentId,
+        toAddress,
+        status: result.status,
+      },
+    });
+  }
+
+  return {
+    channel: 'claworld',
+    messageId: result.body?.turn?.turnId || `turn_${Date.now()}`,
+    chatId: toAddress,
+    timestamp: Date.now(),
+    meta: {
+      sessionId: result.body?.session?.sessionId || null,
+      turnId: result.body?.turn?.turnId || null,
+      conversationKey: result.body?.conversationKey || null,
+      toAddress,
+    },
+  };
+}
+
+function buildRelayJsonPath(pathname, query = {}) {
+  const search = new URLSearchParams();
+  Object.entries(query).forEach(([key, value]) => {
+    const normalized = resolveNormalizedText(value, null);
+    if (normalized) search.set(key, normalized);
+  });
+  const encoded = search.toString();
+  return encoded ? `${pathname}?${encoded}` : pathname;
+}
+
+function createRelayRouteError({
+  result,
+  runtimeConfig,
+  code,
+  publicMessage,
+  message,
+  context = {},
+}) {
+  throw createRuntimeBoundaryError({
+    code,
+    category: 'transport',
+    status: result?.status >= 500 ? 502 : result?.status || 502,
+    message: message || publicMessage,
+    publicMessage,
+    recoverable: true,
+    context: {
+      accountId: runtimeConfig.accountId || null,
+      httpStatus: result?.status || null,
+      backendCode: result?.body?.error || null,
+      backendMessage: result?.body?.message || null,
+      ...context,
+    },
+  });
+}
+
+async function createFriendRequest({
+  runtimeConfig,
+  fromAgentId,
+  toAddress,
+  message = null,
+  metadata = {},
+  fetchImpl,
+}) {
+  const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
+  const result = await fetchJson(fetchImpl, `${baseUrl}/v1/friend-requests`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      ...(runtimeConfig.apiKey ? { 'x-api-key': runtimeConfig.apiKey } : {}),
+      ...buildRuntimeAuthHeaders(runtimeConfig),
+    },
+    body: JSON.stringify({
+      fromAgentId,
+      toAddress,
+      message: normalizeClaworldText(message, null),
+      metadata: metadata && typeof metadata === 'object' && !Array.isArray(metadata) ? metadata : {},
+    }),
+  });
+  if (!result.ok) {
+    createRelayRouteError({
+      result,
+      runtimeConfig,
+      code: 'friend_request_failed',
+      publicMessage: 'failed to create friend request',
+      context: { fromAgentId, toAddress },
+    });
+  }
+  return result.body || {};
+}
+
+async function listFriendRequests({
+  runtimeConfig,
+  agentId,
+  direction = null,
+  status = null,
+  fetchImpl,
+}) {
+  const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
+  const path = buildRelayJsonPath('/v1/friend-requests', {
+    agentId,
+    direction,
+    status,
+  });
+  const result = await fetchJson(fetchImpl, `${baseUrl}${path}`, {
+    method: 'GET',
+    headers: {
+      ...(runtimeConfig.apiKey ? { 'x-api-key': runtimeConfig.apiKey } : {}),
+      ...buildRuntimeAuthHeaders(runtimeConfig),
+    },
+  });
+  if (!result.ok) {
+    createRelayRouteError({
+      result,
+      runtimeConfig,
+      code: 'friend_request_list_failed',
+      publicMessage: 'failed to list friend requests',
+      context: { agentId, direction, status },
+    });
+  }
+  return result.body || {};
+}
+
+async function acceptFriendRequest({
+  runtimeConfig,
+  actorAgentId,
+  friendRequestId,
+  fetchImpl,
+}) {
+  const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
+  const result = await fetchJson(fetchImpl, `${baseUrl}/v1/friend-requests/${encodeURIComponent(friendRequestId)}/accept`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      ...(runtimeConfig.apiKey ? { 'x-api-key': runtimeConfig.apiKey } : {}),
+      ...buildRuntimeAuthHeaders(runtimeConfig),
+    },
+    body: JSON.stringify({ actorAgentId }),
+  });
+  if (!result.ok) {
+    createRelayRouteError({
+      result,
+      runtimeConfig,
+      code: 'friend_request_accept_failed',
+      publicMessage: 'failed to accept friend request',
+      context: { actorAgentId, friendRequestId },
+    });
+  }
+  return result.body || {};
+}
+
+async function rejectFriendRequest({
+  runtimeConfig,
+  actorAgentId,
+  friendRequestId,
+  fetchImpl,
+}) {
+  const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
+  const result = await fetchJson(fetchImpl, `${baseUrl}/v1/friend-requests/${encodeURIComponent(friendRequestId)}/reject`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      ...(runtimeConfig.apiKey ? { 'x-api-key': runtimeConfig.apiKey } : {}),
+      ...buildRuntimeAuthHeaders(runtimeConfig),
+    },
+    body: JSON.stringify({ actorAgentId }),
+  });
+  if (!result.ok) {
+    createRelayRouteError({
+      result,
+      runtimeConfig,
+      code: 'friend_request_reject_failed',
+      publicMessage: 'failed to reject friend request',
+      context: { actorAgentId, friendRequestId },
+    });
+  }
+  return result.body || {};
+}
+
+async function createChatRequest({
+  runtimeConfig,
+  fromAgentId,
+  targetAgentId,
+  openingMessage = null,
+  worldId = null,
+  episodePolicy = null,
+  fetchImpl,
+}) {
+  const normalizedTargetAgentId = normalizeClaworldText(targetAgentId, null);
+  if (!normalizedTargetAgentId) {
+    throw createRuntimeBoundaryError({
+      code: 'tool_input_invalid',
+      category: 'input',
+      status: 400,
+      message: 'claworld chat request target requires targetAgentId',
+      publicMessage: 'claworld chat request target requires targetAgentId',
+      recoverable: true,
+      context: { field: 'targetAgentId' },
+    });
+  }
+  const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
+  const result = await fetchJson(fetchImpl, `${baseUrl}/v1/chat-requests`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      ...(runtimeConfig.apiKey ? { 'x-api-key': runtimeConfig.apiKey } : {}),
+      ...buildRuntimeAuthHeaders(runtimeConfig),
+    },
+    body: JSON.stringify({
+      fromAgentId,
+      targetAgentId: normalizedTargetAgentId,
+      openingMessage: normalizeClaworldText(openingMessage, null),
+      ...(normalizeClaworldText(worldId, null) ? { worldId: normalizeClaworldText(worldId, null) } : {}),
+      ...(episodePolicy && typeof episodePolicy === 'object' && !Array.isArray(episodePolicy)
+        ? { episodePolicy }
+        : {}),
+    }),
+  });
+  if (!result.ok) {
+    createRelayRouteError({
+      result,
+      runtimeConfig,
+      code: 'chat_request_create_failed',
+      publicMessage: 'failed to create chat request',
+      context: { fromAgentId, targetAgentId: normalizedTargetAgentId },
+    });
+  }
+  return result.body || {};
+}
+
+async function listChatRequests({
+  runtimeConfig,
+  agentId,
+  direction = null,
+  fetchImpl,
+}) {
+  const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
+  const path = buildRelayJsonPath('/v1/chat-requests', {
+    agentId,
+    direction,
+  });
+  const result = await fetchJson(fetchImpl, `${baseUrl}${path}`, {
+    method: 'GET',
+    headers: {
+      ...(runtimeConfig.apiKey ? { 'x-api-key': runtimeConfig.apiKey } : {}),
+      ...buildRuntimeAuthHeaders(runtimeConfig),
+    },
+  });
+  if (!result.ok) {
+    createRelayRouteError({
+      result,
+      runtimeConfig,
+      code: 'chat_request_list_failed',
+      publicMessage: 'failed to list chat requests',
+      context: { agentId, direction },
+    });
+  }
+  return result.body || {};
+}
+
+async function acceptChatRequest({
+  runtimeConfig,
+  actorAgentId,
+  chatRequestId,
+  fetchImpl,
+}) {
+  const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
+  const result = await fetchJson(fetchImpl, `${baseUrl}/v1/chat-requests/${encodeURIComponent(chatRequestId)}/accept`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      ...(runtimeConfig.apiKey ? { 'x-api-key': runtimeConfig.apiKey } : {}),
+      ...buildRuntimeAuthHeaders(runtimeConfig),
+    },
+    body: JSON.stringify({ actorAgentId }),
+  });
+  if (!result.ok) {
+    createRelayRouteError({
+      result,
+      runtimeConfig,
+      code: 'chat_request_accept_failed',
+      publicMessage: 'failed to accept chat request',
+      context: { actorAgentId, chatRequestId },
+    });
+  }
+  return result.body || {};
+}
+
+async function syncChatRequestApprovalPolicy({
+  runtimeConfig,
+  fetchImpl,
+  logger,
+}) {
+  const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
+  let result;
+  try {
+    result = await fetchJson(fetchImpl, `${baseUrl}/v1/chat-requests/approval-policy`, {
+      method: 'PUT',
+      headers: {
+        'content-type': 'application/json',
+        ...(runtimeConfig.apiKey ? { 'x-api-key': runtimeConfig.apiKey } : {}),
+        ...buildRuntimeAuthHeaders(runtimeConfig),
+      },
+      body: JSON.stringify({
+        accountId: runtimeConfig.accountId || null,
+        approval: runtimeConfig.approval || {},
+      }),
+    });
+  } catch (error) {
+    logger.warn?.(`[claworld:${runtimeConfig.accountId || 'default'}] approval policy sync failed`, {
+      error: error?.message || String(error),
+      code: error?.code || null,
+      category: error?.category || null,
+    });
+    return {
+      ok: false,
+      status: error?.status || null,
+      body: null,
+      error,
+    };
+  }
+  if (!result.ok) {
+    logger.warn?.(`[claworld:${runtimeConfig.accountId || 'default'}] approval policy sync failed`, {
+      status: result.status,
+      body: result.body,
+    });
+    return {
+      ok: false,
+      status: result.status,
+      body: result.body,
+    };
+  }
+
+  logger.info?.(`[claworld:${runtimeConfig.accountId || 'default'}] approval policy sync ok`, {
+    mode: result.body?.approvalPolicy?.policy?.mode || runtimeConfig.approval?.mode || null,
+    syncedAt: result.body?.approvalPolicy?.syncedAt || null,
+  });
+  return {
+    ok: true,
+    status: result.status,
+    body: result.body,
+  };
+}
+
+function waitForAbort(signal) {
+  return new Promise((resolve) => {
+    if (!signal) return resolve({ reason: 'missing_abort_signal' });
+    if (signal.aborted) return resolve({ reason: 'already_aborted' });
+    signal.addEventListener('abort', () => resolve({ reason: 'abort_signal' }), { once: true });
+  });
+}
+
+function waitForRelayClientClose(relayClient) {
+  return new Promise((resolve) => {
+    if (!relayClient?.once) return resolve({ reason: 'missing_relay_client' });
+    relayClient.once('close', (info = {}) => {
+      resolve({
+        reason: info.reason || 'relay_client_closed',
+        close: info,
+      });
+    });
+  });
+}
+
+function isNonRecoverableBootstrapHoldError(error) {
+  return Boolean(
+    error
+    && error.recoverable === false
+    && ['auth', 'bootstrap', 'config', 'conflict', 'input', 'policy'].includes(error.category),
+  );
+}
+
+function buildBootstrapHoldMessage(error, runtimeConfig = {}) {
+  if (error?.code === 'agent_code_conflict') {
+    const requestedAgentCode = normalizeClaworldText(
+      error?.context?.requestedAgentCode,
+      normalizeRuntimeRegistration(runtimeConfig).agentCode || null,
+    );
+    return requestedAgentCode
+      ? `Claworld setup blocked: relay agent code ${requestedAgentCode} already exists. Add the bound appToken for this account or choose a different registration.agentCode.`
+      : 'Claworld setup blocked: relay agent code already exists. Add the bound appToken for this account or choose a different registration.agentCode.';
+  }
+
+  const publicMessage = normalizeClaworldText(error?.publicMessage, null);
+  const fallbackMessage = normalizeClaworldText(error?.message, 'relay binding bootstrap failed');
+  return `Claworld setup blocked: ${publicMessage || fallbackMessage}`;
+}
+
+function summarizeObjectShape(value) {
+  if (!value || typeof value !== 'object') return { type: typeof value };
+  const keys = Object.keys(value).sort();
+  return {
+    type: Array.isArray(value) ? 'array' : 'object',
+    keys,
+    hasChannelsClaworld: Boolean(value.channels?.claworld),
+    hasAccounts: Boolean(value.accounts && typeof value.accounts === 'object'),
+    accountId: value.accountId || null,
+    configured: typeof value.configured === 'boolean' ? value.configured : null,
+  };
+}
+
+function hasRelayDispatchSurface(runtime) {
+  return Boolean(
+    runtime?.channel?.routing?.resolveAgentRoute
+    && runtime?.channel?.reply?.finalizeInboundContext
+    && (
+      runtime?.channel?.reply?.dispatchReplyFromConfig
+      || runtime?.channel?.reply?.createReplyDispatcherWithTyping
+    )
+  );
+}
+
+function resolvePluginRuntimeCandidate(contextRuntime) {
+  let globalRuntime = null;
+  try {
+    globalRuntime = getClaworldRuntime();
+  } catch {
+    globalRuntime = null;
+  }
+
+  if (hasRelayDispatchSurface(contextRuntime)) {
+    return {
+      runtime: contextRuntime,
+      runtimeSource: 'context.runtime',
+    };
+  }
+
+  if (hasRelayDispatchSurface(globalRuntime)) {
+    return {
+      runtime: globalRuntime,
+      runtimeSource: 'global_runtime',
+    };
+  }
+
+  if (contextRuntime) {
+    return {
+      runtime: contextRuntime,
+      runtimeSource: 'context.runtime',
+    };
+  }
+
+  if (globalRuntime) {
+    return {
+      runtime: globalRuntime,
+      runtimeSource: 'global_runtime',
+    };
+  }
+
+  return {
+    runtime: null,
+    runtimeSource: 'unavailable',
+  };
+}
+
+function resolveRuntimeConfigSource(context = {}) {
+  const runtimeCfg = context.cfg && typeof context.cfg === 'object' ? context.cfg : null;
+  const accountId = context.accountId || context.account?.accountId || null;
+
+  if (runtimeCfg) {
+    return {
+      sourceType: 'root_cfg',
+      configSource: runtimeCfg,
+      runtimeConfig: resolveClaworldRuntimeConfig(runtimeCfg, accountId),
+    };
+  }
+
+  const accountLike = context.account || context.config || null;
+  if (accountLike) {
+    return {
+      sourceType: 'resolved_account',
+      configSource: accountLike,
+      runtimeConfig: resolveClaworldRuntimeConfig(accountLike, accountId),
+    };
+  }
+
+  return {
+    sourceType: 'empty',
+    configSource: {},
+    runtimeConfig: resolveClaworldRuntimeConfig({}, accountId),
+  };
+}
+
+async function fetchJson(fetchImpl, url, init = {}) {
+  try {
+    const response = await fetchImpl(url, init);
+    let body = null;
+    try {
+      body = await response.json();
+    } catch {
+      body = null;
+    }
+    return { ok: response.ok, status: response.status, body };
+  } catch (error) {
+    throw createRuntimeBoundaryError({
+      code: 'relay_fetch_failed',
+      category: 'transport',
+      status: 502,
+      message: `fetch failed: ${error?.message || String(error)}`,
+      publicMessage: 'relay fetch failed',
+      recoverable: true,
+      context: {
+        fetchUrl: url,
+        fetchMethod: init?.method || 'GET',
+        fetchHeaders: init?.headers || null,
+      },
+      cause: error,
+    });
+  }
+}
+
+async function registerRelayBinding({ runtimeConfig, fetchImpl, logger }) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for relay registration');
+  }
+
+  const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
+  const registration = normalizeRuntimeRegistration(runtimeConfig);
+  const registerResult = await fetchJson(fetchImpl, `${baseUrl}/v1/agents/register`, {
+    method: 'POST',
+    headers: buildRuntimeAuthHeaders(runtimeConfig, {
+      accept: 'application/json',
+      'content-type': 'application/json',
+      ...(runtimeConfig.apiKey ? { 'x-api-key': runtimeConfig.apiKey } : {}),
+    }),
+    body: JSON.stringify({
+      ...(registration.enabled ? { agentCode: registration.agentCode } : {}),
+      ...(registration.displayName ? { displayName: registration.displayName } : {}),
+    }),
+  });
+
+  if (!registerResult.ok) {
+    logger.error?.('[claworld:bootstrap] register relay agent failed', {
+      accountId: runtimeConfig.accountId,
+      status: registerResult.status,
+      body: registerResult.body,
+    });
+
+    const errorCode = normalizeClaworldText(registerResult.body?.error, 'relay_agent_registration_failed');
+    const category = registerResult.status === 401
+      ? 'auth'
+      : registerResult.status === 403
+        ? 'policy'
+        : registerResult.status === 409
+          ? 'conflict'
+          : registerResult.status >= 500
+            ? 'transport'
+            : 'config';
+    const publicMessage = errorCode === 'agent_code_conflict'
+      ? 'relay agent code already exists; reuse its appToken or choose a different registration.agentCode'
+      : errorCode === 'agent_code_mismatch'
+        ? 'configured relay agent code does not match the provided appToken'
+        : 'relay registration failed';
+
+    throw createRuntimeBoundaryError({
+      code: errorCode,
+      category,
+      status: registerResult.status,
+      message: `failed to register relay agent: ${registerResult.status}`,
+      publicMessage,
+      recoverable: registerResult.status >= 500,
+      context: {
+        accountId: runtimeConfig.accountId || null,
+        requestedAgentCode: normalizeClaworldText(
+          registerResult.body?.requestedAgentCode,
+          registration.agentCode || null,
+        ),
+        authenticatedAgentCode: normalizeClaworldText(registerResult.body?.authenticatedAgentCode, null),
+        authenticatedAddress: normalizeClaworldText(registerResult.body?.authenticatedAddress, null),
+        conflictingAgentId: normalizeClaworldText(registerResult.body?.agent?.agentId, null),
+        conflictingAddress: normalizeClaworldText(registerResult.body?.agent?.address, null),
+        appTokenConfigured: Boolean(resolveRuntimeAppToken(runtimeConfig)),
+      },
+    });
+  }
+
+  const registeredAgent = registerResult.body?.agent || null;
+  const appToken = normalizeClaworldText(registerResult.body?.appToken, resolveRuntimeAppToken(runtimeConfig));
+  if (!registeredAgent?.agentId || !appToken) {
+    throw new Error('relay registration did not produce relay agent binding');
+  }
+
+  return {
+    bindingSource: normalizeClaworldText(
+      registerResult.body?.bindingSource,
+      resolveRuntimeAppToken(runtimeConfig) ? 'provided_app_token' : 'created_agent_app_token',
+    ),
+    runtimeConfig: applyRuntimeIdentity(runtimeConfig, {
+      agentId: registeredAgent.agentId,
+      appToken,
+    }),
+    relayAgent: buildRelayAgentSummary(registeredAgent, runtimeConfig),
+  };
+}
+
+async function fetchRelayAgents({ runtimeConfig, fetchImpl, logger }) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for relay agent lookup');
+  }
+
+  const baseUrl = normalizeRelayHttpBaseUrl(runtimeConfig.serverUrl);
+  const result = await fetchJson(fetchImpl, `${baseUrl}/v1/agents`, {
+    headers: {
+      accept: 'application/json',
+      ...(runtimeConfig.apiKey ? { 'x-api-key': runtimeConfig.apiKey } : {}),
+      ...buildRuntimeAuthHeaders(runtimeConfig),
+    },
+  });
+
+  if (!result.ok) {
+    logger.warn?.('[claworld:pairing] relay agent lookup failed', {
+      accountId: runtimeConfig.accountId || null,
+      status: result.status,
+      body: result.body,
+    });
+    throw new Error(`relay agent lookup failed: ${result.status}`);
+  }
+
+  return Array.isArray(result.body?.items) ? result.body.items : [];
+}
+
+async function resolveRelayAgentSummary({
+  runtimeConfig,
+  fetchImpl,
+  logger,
+  agentId = null,
+  agentCode = null,
+  address = null,
+}) {
+  const requestedIdentity = normalizeRelayIdentityInput({
+    runtimeConfig,
+    agentId,
+    agentCode,
+    address,
+  });
+
+  try {
+    const items = await fetchRelayAgents({ runtimeConfig, fetchImpl, logger });
+    const match = items
+      .map((item) => buildRelayAgentSummary(item, runtimeConfig))
+      .find((item) => {
+        if (requestedIdentity.agentId && item.agentId === requestedIdentity.agentId) return true;
+        if (requestedIdentity.agentCode && item.agentCode === requestedIdentity.agentCode) return true;
+        if (requestedIdentity.address && item.address === requestedIdentity.address) return true;
+        if (requestedIdentity.relayLocalCode && item.relayLocalCode === requestedIdentity.relayLocalCode) return true;
+        return false;
+      }) || null;
+
+    if (match) {
+      return {
+        ...match,
+        resolved: true,
+        resolutionSource: requestedIdentity.agentId && match.agentId === requestedIdentity.agentId
+          ? 'agentId'
+          : requestedIdentity.agentCode && match.agentCode === requestedIdentity.agentCode
+            ? 'agentCode'
+            : requestedIdentity.address && match.address === requestedIdentity.address
+              ? 'address'
+              : 'relayLocalCode',
+      };
+    }
+  } catch {
+    // Fallback below keeps pairing/send tools usable even when lookup fails.
+  }
+
+  const canInferFallbackAgentCode = Boolean(
+    requestedIdentity.agentCode
+    || requestedIdentity.address
+    || requestedIdentity.relayLocalCode,
+  );
+  const fallbackAgentCode = requestedIdentity.agentCode
+    || (canInferFallbackAgentCode ? buildCanonicalRelayAgentCode(runtimeConfig.localAgent?.agentCode, runtimeConfig) : null)
+    || (canInferFallbackAgentCode ? buildCanonicalRelayAgentCode(runtimeConfig.accountId, runtimeConfig) : null);
+  const parsedFallbackAgentCode = parseCanonicalRelayAgentCode(fallbackAgentCode);
+
+  return {
+    agentId: requestedIdentity.agentId,
+    agentCode: fallbackAgentCode,
+    relayLocalCode: requestedIdentity.relayLocalCode
+      || parsedFallbackAgentCode?.relayLocalCode
+      || normalizeRelayLocalAgentCode(runtimeConfig.localAgent?.agentCode, null)
+      || null,
+    domain: requestedIdentity.domain
+      || parsedFallbackAgentCode?.domain
+      || normalizeRelayDomainName(inferRelayDomain(runtimeConfig), null),
+    address: requestedIdentity.address || fallbackAgentCode || null,
+    displayName: normalizeClaworldText(runtimeConfig.localAgent?.displayName, null),
+    discoverable: null,
+    contactable: null,
+    online: null,
+    resolved: false,
+    resolutionSource: 'fallback',
+  };
+}
+
+async function ensureAgentPairing({ runtimeConfig, fetchImpl, logger }) {
+  const binding = await ensureRelayBinding({ runtimeConfig, fetchImpl, logger });
+  const pairedRuntimeConfig = binding.runtimeConfig;
+  const relayAgentId = normalizeClaworldText(pairedRuntimeConfig.relay?.agentId, null);
+  const relayAgentCode = normalizeRelayLocalAgentCode(
+    pairedRuntimeConfig.localAgent?.agentCode,
+    normalizeRelayLocalAgentCode(pairedRuntimeConfig.accountId, null),
+  );
+
+  if (!relayAgentId) {
+    return {
+      status: 'unpaired',
+      reason: 'missing_app_token_or_registration',
+      bindingSource: binding.bindingSource,
+      runtimeConfig: pairedRuntimeConfig,
+      relayAgent: await resolveRelayAgentSummary({
+        runtimeConfig: pairedRuntimeConfig,
+        fetchImpl,
+        logger,
+        agentId: relayAgentId,
+        agentCode: relayAgentCode,
+      }),
+    };
+  }
+
+  return {
+    status: 'paired',
+    reason: null,
+    bindingSource: binding.bindingSource,
+    runtimeConfig: pairedRuntimeConfig,
+    relayAgent: await resolveRelayAgentSummary({
+      runtimeConfig: pairedRuntimeConfig,
+      fetchImpl,
+      logger,
+      agentId: relayAgentId,
+      agentCode: relayAgentCode,
+    }),
+  };
+}
+
+async function fetchPostSetupWorldDirectory({ cfg, accountId, runtimeConfig, limit = null, sort = null, page = null, fetchImpl, logger }) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for claworld product-shell helper');
+  }
+
+  const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg || {}, accountId || null);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+  const requestUrl = new URL(`${baseUrl}/v1/worlds`);
+  if (limit != null) requestUrl.searchParams.set('limit', String(limit));
+  if (sort) requestUrl.searchParams.set('sort', String(sort));
+  if (page != null) requestUrl.searchParams.set('page', String(page));
+  const worlds = await fetchJson(fetchImpl, requestUrl.toString(), {
+    headers: {
+      accept: 'application/json',
+      ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+      ...buildRuntimeAuthHeaders(resolvedRuntimeConfig),
+    },
+  });
+
+  if (!worlds.ok) {
+    logger.error?.('[claworld:product-shell] world directory fetch failed', {
+      status: worlds.status,
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      body: worlds.body,
+    });
+    throw new Error(`claworld product-shell world fetch failed: ${worlds.status}`);
+  }
+
+  return buildPostSetupWorldDirectory(worlds.body, {
+    accountId: resolvedRuntimeConfig.accountId || accountId || null,
+  });
+}
+
+async function ensureRelayBinding({ runtimeConfig, fetchImpl, logger }) {
+  const normalizedRuntimeConfig = applyRuntimeIdentity(runtimeConfig);
+  const registration = normalizeRuntimeRegistration(normalizedRuntimeConfig);
+  const appToken = resolveRuntimeAppToken(normalizedRuntimeConfig);
+
+  if (appToken && normalizedRuntimeConfig.relay?.agentId) {
+    return {
+      runtimeConfig: normalizedRuntimeConfig,
+      bindingSource: 'configured_app_token',
+    };
+  }
+
+  if (!appToken && !registration.enabled) {
+    return { runtimeConfig: normalizedRuntimeConfig, bindingSource: 'no_registration_context' };
+  }
+
+  logger.info?.('[claworld:bootstrap] ensureRelayBinding start', {
+    accountId: normalizedRuntimeConfig.accountId,
+    serverUrl: normalizedRuntimeConfig.serverUrl,
+    appTokenConfigured: Boolean(appToken),
+    registrationEnabled: registration.enabled,
+    agentCode: registration.agentCode || null,
+    hasRelayAgentId: Boolean(normalizedRuntimeConfig.relay?.agentId),
+  });
+
+  return await registerRelayBinding({
+    runtimeConfig: normalizedRuntimeConfig,
+    fetchImpl,
+    logger,
+  });
+}
+
+function resolveSessionCreatedWorldId(event = {}) {
+  const session = event?.raw?.data && typeof event.raw.data === 'object' ? event.raw.data : {};
+  const metadata = session.metadata && typeof session.metadata === 'object' ? session.metadata : {};
+  const candidateWorldId = [
+    metadata.worldId,
+    metadata.worldContext?.worldId,
+    session.worldContext?.worldId,
+    session.worldId,
+    session.session?.metadata?.worldId,
+    session.session?.metadata?.worldContext?.worldId,
+    session.session?.worldContext?.worldId,
+    session.session?.worldId,
+    event?.inboundEnvelope?.metadata?.worldId,
+    event?.inboundEnvelope?.metadata?.worldContext?.worldId,
+    event?.inboundEnvelope?.metadata?.session?.worldId,
+    event?.inboundEnvelope?.metadata?.session?.metadata?.worldId,
+    event?.inboundEnvelope?.metadata?.session?.metadata?.worldContext?.worldId,
+  ].map((value) => resolveNormalizedText(value, null)).find(Boolean);
+  return candidateWorldId || null;
+}
+
+function resolveTurnWorldId(event = {}) {
+  const turnData = event?.raw?.data && typeof event.raw.data === 'object' ? event.raw.data : {};
+  const metadata = turnData.metadata && typeof turnData.metadata === 'object' ? turnData.metadata : {};
+  const candidateWorldId = [
+    metadata.worldId,
+    metadata.worldContext?.worldId,
+    turnData.worldContext?.worldId,
+    turnData.worldId,
+    turnData.session?.metadata?.worldId,
+    turnData.session?.metadata?.worldContext?.worldId,
+    turnData.session?.worldContext?.worldId,
+    turnData.session?.worldId,
+    event?.inboundEnvelope?.metadata?.worldId,
+    event?.inboundEnvelope?.metadata?.worldContext?.worldId,
+    event?.inboundEnvelope?.metadata?.session?.worldId,
+    event?.inboundEnvelope?.metadata?.session?.metadata?.worldId,
+    event?.inboundEnvelope?.metadata?.session?.metadata?.worldContext?.worldId,
+  ].map((value) => resolveNormalizedText(value, null)).find(Boolean);
+  return candidateWorldId || null;
+}
+
+function resolveAcceptedChatKickoffBundle(event = {}) {
+  const turnData = event?.raw?.data && typeof event.raw.data === 'object' ? event.raw.data : {};
+  if (turnData.acceptedChatKickoff && typeof turnData.acceptedChatKickoff === 'object' && !Array.isArray(turnData.acceptedChatKickoff)) {
+    return turnData.acceptedChatKickoff;
+  }
+  const payload = turnData.payload && typeof turnData.payload === 'object' && !Array.isArray(turnData.payload)
+    ? turnData.payload
+    : {};
+  if (payload.kickoffBundle && typeof payload.kickoffBundle === 'object' && !Array.isArray(payload.kickoffBundle)) {
+    return payload.kickoffBundle;
+  }
+  return null;
+}
+
+function resolveAcceptedChatKickoffRuntimeContext(event = {}, { bundle = null, localAgentId = null, fallback = 'recipient' } = {}) {
+  const turnData = event?.raw?.data && typeof event.raw.data === 'object' ? event.raw.data : {};
+  if (
+    turnData.acceptedChatKickoffRuntimeContext
+    && typeof turnData.acceptedChatKickoffRuntimeContext === 'object'
+    && !Array.isArray(turnData.acceptedChatKickoffRuntimeContext)
+  ) {
+    return turnData.acceptedChatKickoffRuntimeContext;
+  }
+  const payload = turnData.payload && typeof turnData.payload === 'object' && !Array.isArray(turnData.payload)
+    ? turnData.payload
+    : {};
+  if (
+    payload.acceptedChatKickoffRuntimeContext
+    && typeof payload.acceptedChatKickoffRuntimeContext === 'object'
+    && !Array.isArray(payload.acceptedChatKickoffRuntimeContext)
+  ) {
+    return payload.acceptedChatKickoffRuntimeContext;
+  }
+  if (!bundle) return null;
+  return readAcceptedChatKickoffRuntimeContext(bundle, {
+    viewer: resolveAcceptedChatKickoffViewer(bundle, {
+      localAgentId,
+      fallback,
+    }),
+  });
+}
+
+function buildWorldAwareSessionKey(sessionKey, worldId = null) {
+  if (!worldId) return sessionKey;
+  return `${sessionKey}:world:${worldId}`;
+}
+
+function buildSessionWorldCacheKey(runtimeAccountId, sessionId) {
+  const accountId = resolveNormalizedText(runtimeAccountId, 'default');
+  if (!sessionId || !accountId) return null;
+  return `${accountId}:${sessionId}`;
+}
+
+function resolveSessionCreatedPeerAgentId(session = {}, localRelayAgentId = null) {
+  const agentAId = normalizeClaworldText(session.agentAId, null);
+  const agentBId = normalizeClaworldText(session.agentBId, null);
+  const localAgentId = normalizeClaworldText(localRelayAgentId, null);
+
+  if (localAgentId && agentAId === localAgentId) return agentBId;
+  if (localAgentId && agentBId === localAgentId) return agentAId;
+  return agentAId || agentBId || null;
+}
+
+async function maybeInjectWorldSessionStartupContext({
+  runtime,
+  cfg,
+  runtimeConfig,
+  runtimeAccountId,
+  event,
+  logger,
+  sessionIdToWorldId,
+} = {}) {
+  const worldCache = sessionIdToWorldId || null;
+  if (!runtime?.system?.enqueueSystemEvent || !runtime?.channel?.routing?.resolveAgentRoute) {
+    return { skipped: true, reason: 'missing_runtime_system_or_routing' };
+  }
+
+  const session = event?.raw?.data && typeof event.raw.data === 'object' ? event.raw.data : {};
+  const worldId = resolveSessionCreatedWorldId(event);
+  if (!worldId) {
+    return { skipped: true, reason: 'not_world_scoped' };
+  }
+  const sessionLookupKey = buildSessionWorldCacheKey(runtimeAccountId, session.sessionId);
+  if (sessionLookupKey && worldCache) {
+    worldCache.set(sessionLookupKey, worldId);
+  }
+
+  const peerAgentId = resolveSessionCreatedPeerAgentId(session, runtimeConfig?.relay?.agentId || null);
+  if (!peerAgentId) {
+    return { skipped: true, reason: 'peer_agent_unresolved' };
+  }
+
+  const currentCfg = cfg || await runtime.config?.loadConfig?.() || {};
+  const routePeerId = resolveRelayAddress(peerAgentId, runtimeConfig);
+  const route = runtime.channel.routing.resolveAgentRoute({
+    cfg: currentCfg,
+    channel: 'claworld',
+    accountId: runtimeConfig.accountId,
+    peer: { kind: 'direct', id: routePeerId || peerAgentId },
+  }) || {};
+  const sessionKey = route.sessionKey || `agent:${route.agentId || runtimeConfig.accountId}:main`;
+  const worldSessionKey = buildWorldAwareSessionKey(sessionKey, worldId);
+  const enqueueResult = enqueueBackendGuidance({
+    runtime,
+    sessionKey: worldSessionKey,
+    payload: session,
+  });
+  if (enqueueResult.skipped) {
+    return { skipped: true, reason: enqueueResult.reason, worldId, sessionKey: worldSessionKey };
+  }
+
+  logger.info?.(`[claworld:${runtimeAccountId}] injected backend-authored world startup guidance`, {
+    worldId,
+    sessionId: session.sessionId || null,
+    sessionKey: worldSessionKey,
+    routePeerId: routePeerId || peerAgentId,
+    guidanceCount: enqueueResult.count,
+  });
+
+  return {
+    skipped: false,
+    ok: true,
+    worldId,
+    sessionKey: worldSessionKey,
+  };
+}
+
+function buildRelayInboundEnvelope({
+  runtime,
+  currentCfg,
+  runtimeAccountId,
+  remoteIdentity,
+  incomingText,
+  contextText = null,
+  commandText = null,
+  sessionId,
+  turnId,
+  relayEvent,
+  mode = 'direct',
+  worldId = null,
+  conversationKey = null,
+}) {
+  const envelopeOptions = runtime?.channel?.reply?.resolveEnvelopeFormatOptions
+    ? runtime.channel.reply.resolveEnvelopeFormatOptions(currentCfg)
+    : undefined;
+  const bodyText = [
+    String(contextText || '').trim(),
+    String(incomingText || '').trim(),
+  ].filter(Boolean).join('\n\n');
+  const remoteLabel = String(remoteIdentity || 'unknown-peer').trim() || 'unknown-peer';
+  const systemLines = [
+    `[claworld peer ${remoteLabel}]`,
+    `[claworld mode ${mode}]`,
+    ...(worldId ? [`[claworld world ${worldId}]`] : []),
+    ...(conversationKey ? [`[claworld conversation ${conversationKey}]`] : []),
+    `[claworld session ${sessionId}]`,
+    `[claworld turn ${turnId}]`,
+    `[relay event ${relayEvent}]`,
+  ];
+  const rawBody = `${bodyText}\n\n${systemLines.join('\n')}`;
+  const normalizedCommandText = String(commandText || '').trim();
+  const commandBody = normalizedCommandText || rawBody;
+
+  if (runtime?.channel?.reply?.formatAgentEnvelope) {
+    return {
+      Body: runtime.channel.reply.formatAgentEnvelope({
+        channel: 'Claworld',
+        from: remoteLabel,
+        timestamp: new Date(),
+        envelope: envelopeOptions,
+        body: rawBody,
+      }),
+      RawBody: rawBody,
+      CommandBody: commandBody,
+      ContextLines: systemLines,
+    };
+  }
+
+  return {
+    Body: `${remoteLabel}: ${rawBody}`,
+    RawBody: rawBody,
+    CommandBody: commandBody,
+    ContextLines: systemLines,
+  };
+}
+
+function createRelayReplyDispatcher({
+  runtime,
+  currentCfg,
+  route,
+  relayClient,
+  sessionId,
+  turnId,
+  relayEvent,
+  localRelayAgentId,
+  allowRelayContinuation = true,
+  logger,
+  runtimeAccountId,
+}) {
+  const prefixContext = runtime?.channel?.reply?.createReplyPrefixContext
+    ? runtime.channel.reply.createReplyPrefixContext({ cfg: currentCfg, agentId: route.agentId })
+    : { responsePrefix: '', responsePrefixContextProvider: () => ({}) };
+  const humanDelay = runtime?.channel?.reply?.resolveHumanDelayConfig
+    ? runtime.channel.reply.resolveHumanDelayConfig(currentCfg, route.agentId)
+    : undefined;
+
+  let replied = false;
+  let suppressed = false;
+  const finalTexts = [];
+  const blockTexts = [];
+  const runtimeOutputSummary = {
+    counts: {
+      final: 0,
+      block: 0,
+      tool: 0,
+      partial: 0,
+      reasoning: 0,
+      toolStart: 0,
+      assistantMessageStart: 0,
+      reasoningEnd: 0,
+      compactionStart: 0,
+      compactionEnd: 0,
+      operationalNotice: 0,
+    },
+    previews: {
+      final: [],
+      block: [],
+      tool: [],
+      partial: [],
+      reasoning: [],
+      operationalNotice: [],
+    },
+    relayContinuationSource: 'none',
+    relayContinuationPreview: null,
+  };
+
+  const recordRuntimePayload = (kind, payload = {}) => {
+    if (!Object.prototype.hasOwnProperty.call(runtimeOutputSummary.counts, kind)) return;
+    runtimeOutputSummary.counts[kind] += 1;
+    const text = String(payload?.text ?? payload?.body ?? '').trim();
+    if (kind === 'final') {
+      if (text) {
+        finalTexts.push(text);
+        appendRuntimeOutputPreview(runtimeOutputSummary.previews.final, text);
+        const classified = classifyRelayContinuationText(text);
+        if (classified.operational) {
+          runtimeOutputSummary.counts.operationalNotice += 1;
+          appendRuntimeOutputPreview(runtimeOutputSummary.previews.operationalNotice, text);
+        }
+      }
+      return;
+    }
+    if (kind === 'block') {
+      if (text) {
+        blockTexts.push(text);
+        appendRuntimeOutputPreview(runtimeOutputSummary.previews.block, text);
+      }
+      return;
+    }
+    if (kind === 'tool') {
+      appendRuntimeOutputPreview(runtimeOutputSummary.previews.tool, text);
+    }
+  };
+
+  const recordRuntimeTextEvent = (kind, text) => {
+    if (!Object.prototype.hasOwnProperty.call(runtimeOutputSummary.counts, kind)) return;
+    runtimeOutputSummary.counts[kind] += 1;
+    if (kind === 'partial') {
+      appendRuntimeOutputPreview(runtimeOutputSummary.previews.partial, text);
+      return;
+    }
+    if (kind === 'reasoning') {
+      appendRuntimeOutputPreview(runtimeOutputSummary.previews.reasoning, text);
+    }
+  };
+
+  const recordRuntimeLifecycle = (kind) => {
+    if (!Object.prototype.hasOwnProperty.call(runtimeOutputSummary.counts, kind)) return;
+    runtimeOutputSummary.counts[kind] += 1;
+  };
+
+  const flushReply = async (text) => {
+    const controlledReply = extractControlledReply(text);
+    const normalized = String(controlledReply.text || '').trim();
+    if ((!normalized && !controlledReply.control) || replied || suppressed) return false;
+    if (allowRelayContinuation === false) {
+      suppressed = true;
+      return false;
+    }
+    if (relayEvent === 'turn.reply') {
+      if (!localRelayAgentId) {
+        throw new Error('missing local relay agent id for relay continuation');
+      }
+      const result = await relayClient.createTurn({
+        sessionId,
+        fromAgentId: localRelayAgentId,
+        payload: {
+          text: normalized,
+          source: 'openclaw-autochain',
+          ...(controlledReply.control ? { control: controlledReply.control } : {}),
+        },
+      });
+      if (result.status !== 201) {
+        throw new Error(`failed to create follow-up relay turn: ${result.status}`);
+      }
+    } else {
+      relayClient.sendTurnReply({
+        sessionId,
+        messageId: turnId,
+        replyText: normalized,
+        source: 'openclaw-autochain',
+        ...(controlledReply.control ? { control: controlledReply.control } : {}),
+      });
+    }
+    replied = true;
+    return true;
+  };
+
+  const dispatchApi = runtime.channel.reply.createReplyDispatcherWithTyping({
+    responsePrefix: prefixContext.responsePrefix,
+    responsePrefixContextProvider: prefixContext.responsePrefixContextProvider,
+    humanDelay,
+    deliver: async (payload = {}, info = {}) => {
+      if (info?.kind === 'final') {
+        recordRuntimePayload('final', payload);
+        return;
+      }
+      if (info?.kind === 'block') {
+        recordRuntimePayload('block', payload);
+        return;
+      }
+      if (info?.kind === 'tool') {
+        recordRuntimePayload('tool', payload);
+      }
+    },
+    onError: (error, info) => {
+      logger.error?.(`[claworld:${runtimeAccountId}] turn bridge dispatch error`, {
+        sessionId,
+        turnId,
+        kind: info?.kind || null,
+        error: error?.message || String(error),
+      });
+    },
+  });
+
+  const markDispatchIdle = async () => {
+    if (!replied && !suppressed) {
+      const continuation = buildRelayContinuationText({ finalTexts, blockTexts });
+      runtimeOutputSummary.relayContinuationSource = continuation.source;
+      runtimeOutputSummary.relayContinuationPreview = continuation.text
+        ? previewRuntimeOutputText(continuation.text)
+        : null;
+      const continuationText = continuation.text;
+      if (continuationText) {
+        await flushReply(continuationText);
+      }
+    }
+    await dispatchApi.markDispatchIdle?.();
+  };
+
+  return {
+    dispatcher: dispatchApi.dispatcher,
+    replyOptions: {
+      ...dispatchApi.replyOptions,
+      onPartialReply: async (payload = {}) => {
+        recordRuntimeTextEvent('partial', payload?.text);
+      },
+      onReasoningStream: async (payload = {}) => {
+        recordRuntimeTextEvent('reasoning', payload?.text);
+      },
+      onReasoningEnd: async () => {
+        recordRuntimeLifecycle('reasoningEnd');
+      },
+      onAssistantMessageStart: async () => {
+        recordRuntimeLifecycle('assistantMessageStart');
+      },
+      onToolStart: async () => {
+        recordRuntimeLifecycle('toolStart');
+      },
+      onCompactionStart: async () => {
+        recordRuntimeLifecycle('compactionStart');
+      },
+      onCompactionEnd: async () => {
+        recordRuntimeLifecycle('compactionEnd');
+      },
+    },
+    markDispatchIdle,
+    didReply: () => replied,
+    getRuntimeOutputSummary: () => ({
+      counts: { ...runtimeOutputSummary.counts },
+      previews: {
+        final: [...runtimeOutputSummary.previews.final],
+        block: [...runtimeOutputSummary.previews.block],
+        tool: [...runtimeOutputSummary.previews.tool],
+        partial: [...runtimeOutputSummary.previews.partial],
+        reasoning: [...runtimeOutputSummary.previews.reasoning],
+        operationalNotice: [...runtimeOutputSummary.previews.operationalNotice],
+      },
+      relayContinuationSource: runtimeOutputSummary.relayContinuationSource,
+      relayContinuationPreview: runtimeOutputSummary.relayContinuationPreview,
+    }),
+  };
+}
+
+async function maybeBridgeDeliveredTurn({
+  relayClient,
+  runtimeConfig,
+  runtimeAccountId,
+  event,
+  logger,
+  runtime,
+  cfg,
+  inbound,
+  sessionIdToWorldId,
+}) {
+  const worldCache = sessionIdToWorldId || null;
+  const relayEvent = event?.relayEvent || 'turn.deliver';
+  const turnData = event?.raw?.data || {};
+  const sessionId = turnData.sessionId || event?.inboundEnvelope?.session_id || null;
+  const turnId = turnData.turnId || event?.inboundEnvelope?.event_id || null;
+  const kickoffBundle = resolveAcceptedChatKickoffBundle(event);
+  const payload = turnData.payload && typeof turnData.payload === 'object' && !Array.isArray(turnData.payload)
+    ? turnData.payload
+    : {};
+  const localRelayAgentId = runtimeConfig.relay?.agentId || relayClient?.boundAgentId || null;
+  const kickoffRuntimeContext = resolveAcceptedChatKickoffRuntimeContext(event, {
+    bundle: kickoffBundle,
+    localAgentId: localRelayAgentId,
+    fallback: relayEvent === 'turn.deliver' ? 'sender' : 'recipient',
+  });
+  const incomingText = turnData.payload?.text
+    || event?.inboundEnvelope?.payload?.text
+    || (
+      payload.kind === ACCEPTED_CHAT_KICKOFF_PAYLOAD_KIND
+        ? kickoffRuntimeContext?.text || ''
+        : ''
+    );
+  const fromAgentId = turnData.fromAgentId || event?.inboundEnvelope?.from_agent_id || null;
+  const conversationKey = turnData.conversationKey || null;
+  const bridgedCommandText = payload.kind === ACCEPTED_CHAT_KICKOFF_PAYLOAD_KIND
+    ? kickoffRuntimeContext?.briefText || kickoffBundle?.request?.brief?.text || incomingText
+    : incomingText;
+  const kickoffContextText = relayEvent === 'turn.reply'
+    && kickoffBundle?.kickoffTurnId
+    && kickoffBundle.kickoffTurnId === turnId
+    ? kickoffRuntimeContext?.text || null
+    : null;
+  const senderId = fromAgentId || 'unknown-peer';
+  if (
+    !runtime?.channel?.routing?.resolveAgentRoute
+    || !runtime?.channel?.reply?.finalizeInboundContext
+    || !runtime?.channel?.reply?.dispatchReplyFromConfig
+    || !runtime?.channel?.reply?.createReplyDispatcherWithTyping
+  ) {
+    logger.warn?.(`[claworld:${runtimeAccountId}] skipping relay bridge: missing runtime bridge hooks`, {
+      relayEvent,
+      sessionId,
+      turnId,
+    });
+    return { skipped: true, reason: 'missing_runtime_bridge_hooks' };
+  }
+  if (!sessionId || !turnId || !incomingText) {
+    logger.warn?.(`[claworld:${runtimeAccountId}] skipping relay bridge: missing turn payload`, {
+      relayEvent,
+      sessionId,
+      turnId,
+      hasIncomingText: Boolean(incomingText),
+    });
+    return { skipped: true, reason: 'missing_turn_payload' };
+  }
+
+  const currentCfg = cfg || await runtime.config?.loadConfig?.() || {};
+  const localAddress = resolveRelayAddress(runtimeConfig.accountId || '', runtimeConfig);
+  const remoteAddress = resolveRelayAddress(senderId, runtimeConfig);
+  const routePeerId = remoteAddress || senderId;
+  const worldId = resolveTurnWorldId(event);
+  const sessionLookupKey = buildSessionWorldCacheKey(runtimeAccountId, sessionId);
+  const resolvedWorldId = worldId || (sessionLookupKey ? worldCache?.get(sessionLookupKey) : null);
+  if (sessionLookupKey && resolvedWorldId && worldCache) {
+    worldCache.set(sessionLookupKey, resolvedWorldId);
+  }
+  const route = runtime.channel.routing.resolveAgentRoute({
+    cfg: currentCfg,
+    channel: 'claworld',
+    accountId: runtimeConfig.accountId,
+    peer: { kind: 'direct', id: routePeerId },
+  }) || {};
+  const routed = inbound?.routeInboundEvent?.(event?.inboundEnvelope || {}, {
+    sessionTarget: runtimeConfig.routing?.sessionTarget,
+    fallbackTarget: runtimeConfig.routing?.fallbackTarget,
+    route,
+  }) || null;
+
+  const sessionKey = route.sessionKey || `agent:${route.agentId || runtimeConfig.accountId}:main`;
+  const worldSessionKey = buildWorldAwareSessionKey(sessionKey, resolvedWorldId);
+  const commandAuthorized = shouldAuthorizeBridgedCommand({
+    runtimeConfig,
+    relayEvent,
+    incomingText: bridgedCommandText,
+  });
+  const { Body, RawBody, CommandBody, ContextLines } = buildRelayInboundEnvelope({
+    runtime,
+    currentCfg,
+    runtimeAccountId,
+    remoteIdentity: routePeerId,
+    incomingText,
+    contextText: kickoffContextText,
+    commandText: bridgedCommandText,
+    sessionId,
+    turnId,
+    relayEvent,
+    mode: resolvedWorldId ? 'world' : 'direct',
+    worldId: resolvedWorldId,
+    conversationKey,
+  });
+  const inboundCtx = runtime.channel.reply.finalizeInboundContext({
+    Body,
+    RawBody,
+    CommandBody,
+    BodyForAgent: RawBody,
+    BodyForCommands: CommandBody,
+    From: routePeerId ? `claworld:${routePeerId}` : `claworld:${senderId}`,
+    To: localAddress ? `claworld:${localAddress}` : `claworld:${runtimeConfig.accountId}`,
+    SessionKey: worldSessionKey,
+    AccountId: runtimeConfig.accountId,
+    OriginatingChannel: 'claworld',
+    OriginatingFrom: routePeerId || senderId,
+    // Match OpenClaw DM channel semantics: `To` is the local account surface,
+    // while `OriginatingTo` is the remote peer to reply back to.
+    OriginatingTo: routePeerId || localAddress || runtimeConfig.accountId,
+    ChatType: 'direct',
+    SenderName: routePeerId || senderId,
+    SenderId: routePeerId || senderId,
+    MessageId: turnId,
+    Provider: 'claworld',
+    Surface: 'claworld',
+    ConversationLabel: routePeerId || senderId,
+    Timestamp: Date.now(),
+    MessageSid: turnId,
+    WasMentioned: false,
+    CommandAuthorized: commandAuthorized,
+    RelaySessionId: sessionId,
+    RelayTurnId: turnId,
+    RelayFromAgentId: fromAgentId,
+    UntrustedContext: ContextLines,
+  });
+
+  enqueueBackendGuidance({
+    runtime,
+    sessionKey: worldSessionKey,
+    payload: turnData,
+  });
+
+  logger.info?.(`[claworld:${runtimeAccountId}] bridging ${relayEvent} into agent session`, {
+    sessionId,
+    turnId,
+    routePeerId,
+    routeSessionKey: worldSessionKey,
+    routeStatus: routed?.status || null,
+    bodyPreview: String(Body || '').slice(0, 240),
+    rawBodyPreview: String(RawBody || '').slice(0, 240),
+    inboundAccountId: inboundCtx?.AccountId || null,
+    inboundTo: inboundCtx?.To || null,
+    inboundFrom: inboundCtx?.From || null,
+    originatingTo: inboundCtx?.OriginatingTo || null,
+    originatingFrom: inboundCtx?.OriginatingFrom || null,
+    commandAuthorized,
+  });
+
+  const { dispatcher, replyOptions, markDispatchIdle, didReply, getRuntimeOutputSummary } = createRelayReplyDispatcher({
+    runtime,
+    currentCfg,
+    route,
+    relayClient,
+    sessionId,
+    turnId,
+    relayEvent,
+    localRelayAgentId,
+    allowRelayContinuation: resolveContinuationState(turnData).allowed !== false,
+    logger,
+    runtimeAccountId,
+  });
+  const dispatchResult = await runtime.channel.reply.dispatchReplyFromConfig({
+    ctx: inboundCtx,
+    cfg: currentCfg,
+    dispatcher,
+    replyOptions,
+  });
+  await markDispatchIdle();
+  const replied = didReply();
+  const runtimeOutputSummary = getRuntimeOutputSummary();
+
+  logger.info?.(`[claworld:${runtimeAccountId}] relay message bridge completed`, {
+    sessionId,
+    turnId,
+    relayEvent,
+    queuedFinal: Boolean(dispatchResult?.queuedFinal),
+    replied,
+    routeSessionKey: worldSessionKey,
+    routeStatus: routed?.status || null,
+    runtimeOutputSummary,
+  });
+
+  return {
+    skipped: false,
+    ok: true,
+    replied,
+    queuedFinal: Boolean(dispatchResult?.queuedFinal),
+    routeSessionKey: worldSessionKey,
+    routeStatus: routed?.status || null,
+  };
+}
+
+export function createClaworldChannelPlugin({
+  logger = console,
+  relayClientFactory = createClaworldRelayClient,
+  fetchImpl = globalThis.fetch?.bind(globalThis),
+} = {}) {
+  const protocol = createRelayEventProtocol();
+  const inbound = createInboundSessionRouter();
+  const outbound = createOutboundSessionBridge();
+  const results = createCanonicalResultBuilder();
+  const demo = createDemoSessionBootstrap();
+  const relayClients = new Map();
+  const lifecycles = new Map();
+  const accountRuntimeContexts = new Map();
+  const sessionIdToWorldId = new Map();
+
+  async function persistRuntimeAppToken({ runtime, accountId, appToken }) {
+    if (!runtime?.config?.loadConfig || !runtime?.config?.writeConfigFile) {
+      return { skipped: true, reason: 'missing_runtime_config_io' };
+    }
+    if (!accountId || !appToken) {
+      return { skipped: true, reason: 'missing_account_or_token' };
+    }
+
+    const currentCfg = await runtime.config.loadConfig();
+    const nextCfg = JSON.parse(JSON.stringify(currentCfg || {}));
+    nextCfg.channels = nextCfg.channels && typeof nextCfg.channels === 'object' && !Array.isArray(nextCfg.channels)
+      ? nextCfg.channels
+      : {};
+    const claworldRoot = nextCfg.channels.claworld && typeof nextCfg.channels.claworld === 'object' && !Array.isArray(nextCfg.channels.claworld)
+      ? nextCfg.channels.claworld
+      : {};
+    const accounts = claworldRoot.accounts && typeof claworldRoot.accounts === 'object' && !Array.isArray(claworldRoot.accounts)
+      ? claworldRoot.accounts
+      : {};
+    const account = accounts[accountId] && typeof accounts[accountId] === 'object' && !Array.isArray(accounts[accountId])
+      ? accounts[accountId]
+      : {};
+
+    if (normalizeClaworldText(account.appToken, null) === appToken) {
+      return { skipped: true, reason: 'already_persisted' };
+    }
+
+    accounts[accountId] = {
+      ...account,
+      appToken,
+    };
+    claworldRoot.accounts = accounts;
+    nextCfg.channels.claworld = claworldRoot;
+    await runtime.config.writeConfigFile(nextCfg);
+    return { skipped: false, ok: true };
+  }
+
+  async function resolveBoundRuntimeContext(context = {}) {
+    const cfg = context.cfg || {};
+    const accountId = context.accountId || null;
+    const runtimeContext = accountRuntimeContexts.get(accountId || 'default') || null;
+    let runtimeConfig = runtimeContext?.runtimeConfig || context.runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+    if (runtimeContext?.runtimeConfig && !runtimeContext?.deferredFailure) {
+      return {
+        ...context,
+        cfg: runtimeContext.cfg || cfg,
+        accountId: runtimeConfig.accountId || accountId || null,
+        runtimeConfig,
+        agentId: context.agentId || runtimeConfig.relay?.agentId || null,
+        bindingSource: 'runtime_context',
+      };
+    }
+    const binding = await ensureRelayBinding({ runtimeConfig, fetchImpl, logger });
+    runtimeConfig = binding.runtimeConfig;
+    return {
+      ...context,
+      cfg,
+      accountId: runtimeConfig.accountId || accountId || null,
+      runtimeConfig,
+      agentId: context.agentId || runtimeConfig.relay?.agentId || null,
+      bindingSource: binding.bindingSource,
+    };
+  }
+
+  function clearSessionWorldCache(runtimeAccountId = 'default') {
+    const accountId = resolveNormalizedText(runtimeAccountId, 'default');
+    const prefix = `${accountId}:`;
+    Array.from(sessionIdToWorldId.keys()).forEach((cacheKey) => {
+      if (cacheKey.startsWith(prefix)) {
+        sessionIdToWorldId.delete(cacheKey);
+      }
+    });
+  }
+
+  function getAccountLifecycle(accountKey = 'default') {
+    if (lifecycles.has(accountKey)) return lifecycles.get(accountKey);
+
+    const lifecycle = createClaworldLifecycleManager({
+      logger,
+      connect: async (context = {}) => {
+        const runtimeAccountId = String(context.accountId || context.account?.accountId || accountKey);
+
+        logger.info?.(`[claworld:${runtimeAccountId}] startAccount invoked`, {
+          accountId: context.accountId || null,
+          hasAbortSignal: Boolean(context.abortSignal),
+          hasAccount: Boolean(context.account),
+          hasConfig: Boolean(context.config),
+          hasCfg: Boolean(context.cfg),
+          accountShape: summarizeObjectShape(context.account),
+          configShape: summarizeObjectShape(context.config),
+          cfgShape: summarizeObjectShape(context.cfg),
+        });
+
+        const { sourceType, configSource, runtimeConfig: initialRuntimeConfig } = resolveRuntimeConfigSource(context);
+        let runtimeConfig = initialRuntimeConfig;
+        logger.info?.(`[claworld:${runtimeAccountId}] resolved runtime config source`, {
+          sourceType,
+          configSourceShape: summarizeObjectShape(configSource),
+          runtimeConfigShape: summarizeObjectShape(runtimeConfig),
+        });
+
+        const validation = validateClaworldChannelConfig(configSource, context.accountId);
+        if (!validation.ok && sourceType !== 'root_cfg') {
+          logger.warn?.(`[claworld:${runtimeAccountId}] non-root runtime source would not validate as full cfg`, {
+            sourceType,
+            errors: validation.errors,
+          });
+        }
+
+        let binding;
+        try {
+          binding = await ensureRelayBinding({ runtimeConfig, fetchImpl, logger });
+        } catch (error) {
+          const normalized = normalizeRuntimeBoundaryError(error, {
+            code: 'claworld_relay_binding_failed',
+            category: 'bootstrap',
+            message: 'claworld relay binding bootstrap failed',
+            publicMessage: 'claworld relay binding bootstrap failed',
+            recoverable: true,
+            context: {
+              accountId: runtimeAccountId,
+              stage: 'ensureRelayBinding',
+            },
+          });
+          if (!isNonRecoverableBootstrapHoldError(normalized)) {
+            throw normalized;
+          }
+
+          const { runtime: deferredRuntime } = resolvePluginRuntimeCandidate(context.runtime || null);
+          const deferredFailure = serializeRuntimeBoundaryError(normalized);
+          const holdMessage = buildBootstrapHoldMessage(normalized, runtimeConfig);
+          accountRuntimeContexts.set(accountKey, {
+            runtime: deferredRuntime,
+            cfg: context.cfg || null,
+            runtimeConfig,
+            deferredFailure,
+            deferredErrorMessage: holdMessage,
+          });
+          context.setStatus?.({
+            accountId: runtimeAccountId,
+            configured: false,
+            connected: false,
+            running: false,
+            restartPending: false,
+            lastError: holdMessage,
+          });
+          logger.warn?.(`[claworld:${runtimeAccountId}] relay binding requires operator setup; holding runtime`, {
+            code: normalized.code,
+            category: normalized.category,
+            status: normalized.status,
+            requestedAgentCode: normalized.context?.requestedAgentCode || null,
+          });
+          return {
+            startedDeferred: true,
+            reason: 'bootstrap_setup_required',
+            runtimeConfig,
+            deferredFailure,
+          };
+        }
+        runtimeConfig = binding.runtimeConfig;
+        logger.info?.(`[claworld:${runtimeAccountId}] relay binding ready`, {
+          bindingSource: binding.bindingSource,
+          relayAgentId: runtimeConfig.relay?.agentId || null,
+          hasAppToken: Boolean(resolveRuntimeAppToken(runtimeConfig)),
+        });
+
+        const relayAgentId = context.agentId || runtimeConfig.relay?.agentId || null;
+        const relayCredential = context.credential || (resolveRuntimeAppToken(runtimeConfig)
+          ? { type: 'agent_token', token: resolveRuntimeAppToken(runtimeConfig) }
+          : null);
+
+        if (!relayAgentId) {
+          logger.warn?.(`[claworld:${runtimeAccountId}] missing relay runtime context; deferring connect`);
+          return { startedDeferred: true, reason: 'missing_runtime_context', runtimeConfig };
+        }
+
+        const runtimeResolution = resolvePluginRuntimeCandidate(context.runtime || null);
+        const pluginRuntime = runtimeResolution.runtime;
+        const runtimeSource = runtimeResolution.runtimeSource;
+
+        logger.info?.(`[claworld:${runtimeAccountId}] runtime surface resolved`, {
+          runtimeSource,
+        });
+
+        if (binding.bindingSource !== 'configured_app_token') {
+          try {
+            const persisted = await persistRuntimeAppToken({
+              runtime: pluginRuntime,
+              accountId: runtimeConfig.accountId,
+              appToken: resolveRuntimeAppToken(runtimeConfig),
+            });
+            if (!persisted.skipped) {
+              logger.info?.(`[claworld:${runtimeAccountId}] persisted runtime appToken`, {
+                accountId: runtimeConfig.accountId,
+              });
+            }
+          } catch (error) {
+            logger.warn?.(`[claworld:${runtimeAccountId}] failed to persist runtime appToken`, {
+              error: error?.message || String(error),
+            });
+          }
+        }
+
+        await syncChatRequestApprovalPolicy({
+          runtimeConfig,
+          fetchImpl,
+          logger,
+        });
+
+        accountRuntimeContexts.set(accountKey, {
+          runtime: pluginRuntime,
+          cfg: context.cfg || null,
+          runtimeConfig,
+          deferredFailure: null,
+          deferredErrorMessage: null,
+        });
+
+        const relayClient = relayClientFactory({ logger, inbound, outbound, protocol });
+        relayClients.set(accountKey, relayClient);
+
+        relayClient.on?.('close', (info = {}) => {
+          logger.warn?.(`[claworld:${runtimeAccountId}] relay websocket closed`, info);
+        });
+        relayClient.on?.('runtime_event', (event) => {
+          logger.debug?.(`[claworld:${runtimeAccountId}] inbound relay event`, {
+            relayEvent: event?.relayEvent,
+            target: event?.route?.target || null,
+            sessionId: event?.inboundEnvelope?.session_id || null,
+          });
+
+          if (event?.relayEvent === 'session.created') {
+            const runtimeContext = accountRuntimeContexts.get(accountKey) || {};
+            maybeInjectWorldSessionStartupContext({
+              runtime: runtimeContext.runtime,
+              cfg: runtimeContext.cfg,
+              runtimeConfig,
+              runtimeAccountId,
+              event,
+              logger,
+              sessionIdToWorldId,
+            }).catch((error) => {
+              logger.error?.(`[claworld:${runtimeAccountId}] world startup injection exception`, {
+                error: error?.message || String(error),
+              });
+            });
+          }
+
+          if (event?.relayEvent === 'turn.deliver') {
+            const runtimeContext = accountRuntimeContexts.get(accountKey) || {};
+            maybeBridgeDeliveredTurn({
+              relayClient,
+              runtimeConfig,
+              runtimeAccountId,
+              event,
+              logger,
+              runtime: runtimeContext.runtime,
+              cfg: runtimeContext.cfg,
+              inbound,
+              sessionIdToWorldId,
+            }).catch((error) => {
+              logger.error?.(`[claworld:${runtimeAccountId}] turn bridge exception`, {
+                error: error?.message || String(error),
+              });
+            });
+          }
+
+          if (event?.relayEvent === 'turn.reply') {
+            const runtimeContext = accountRuntimeContexts.get(accountKey) || {};
+            maybeBridgeDeliveredTurn({
+              relayClient,
+              runtimeConfig,
+              runtimeAccountId,
+              event,
+              logger,
+              runtime: runtimeContext.runtime,
+              cfg: runtimeContext.cfg,
+              inbound,
+              sessionIdToWorldId,
+            }).catch((error) => {
+              logger.error?.(`[claworld:${runtimeAccountId}] reply bridge exception`, {
+                error: error?.message || String(error),
+              });
+            });
+          }
+        });
+
+        if (context.autoConnect === false) {
+          logger.info?.(`[claworld:${runtimeAccountId}] lifecycle started in deferred mode (autoConnect=false)`);
+          return { startedDeferred: true, runtimeConfig, relayClient };
+        }
+
+        logger.info?.(`[claworld:${runtimeAccountId}] connecting relay websocket ...`);
+        await relayClient.connect({
+          config: runtimeConfig,
+          agentId: relayAgentId,
+          credential: relayCredential,
+          clientVersion: context.clientVersion,
+          sessionTarget: context.sessionTarget || runtimeConfig.routing?.sessionTarget,
+          fallbackTarget: context.fallbackTarget || runtimeConfig.routing?.fallbackTarget,
+        });
+        logger.info?.(`[claworld:${runtimeAccountId}] auth ok`);
+        return relayClient;
+      },
+      disconnect: async ({ reason }) => {
+        const relayClient = relayClients.get(accountKey);
+        if (relayClient) {
+          await relayClient.close(reason);
+          relayClients.delete(accountKey);
+        }
+        accountRuntimeContexts.delete(accountKey);
+        clearSessionWorldCache(accountKey);
+      },
+    });
+
+    lifecycles.set(accountKey, lifecycle);
+    return lifecycle;
+  }
+
+  async function runAccountLifecycle(context = {}) {
+    const accountKey = String(context.accountId || context.account?.accountId || 'default');
+    const lifecycle = getAccountLifecycle(accountKey);
+    const started = await lifecycle.start(context);
+    const runtimeAccountId = String(
+      context.accountId
+      || context.account?.accountId
+      || started?.connection?.runtimeConfig?.accountId
+      || accountKey
+    );
+
+    if (!context.abortSignal) {
+      logger.warn?.(`[claworld:${runtimeAccountId}] no abortSignal; startAccount will behave as a short-lived start call`);
+      return started;
+    }
+
+    if (context.abortSignal.aborted) {
+      logger.info?.(`[claworld:${runtimeAccountId}] abort already signaled before runtime entered steady state`);
+      await lifecycle.stop('abort_before_run');
+      return started;
+    }
+
+    const startedDeferred = Boolean(started?.connection?.startedDeferred);
+    logger.info?.(
+      `[claworld:${runtimeAccountId}] account runtime started; waiting for ${
+        startedDeferred ? 'abort while setup is deferred' : 'abort'
+      }`,
+    );
+    const stopReason = startedDeferred
+      ? await waitForAbort(context.abortSignal)
+      : await Promise.race([
+        waitForAbort(context.abortSignal),
+        waitForRelayClientClose(started?.connection),
+      ]);
+
+    if (stopReason?.reason === 'abort_signal') {
+      logger.info?.(`[claworld:${runtimeAccountId}] abort signal received, stopping`);
+      await lifecycle.stop('abort_signal');
+      return started;
+    }
+
+    logger.warn?.(`[claworld:${runtimeAccountId}] account runtime ended before abort`, stopReason);
+    await lifecycle.stop(stopReason?.reason || 'runtime_stopped');
+    return started;
+  }
+
+  function createStatusSnapshot() {
+    const configuredAccounts = new Set([
+      ...listClaworldAccountIds({ channels: { claworld: { accounts: {} } } }),
+      ...Array.from(accountRuntimeContexts.keys()),
+      ...Array.from(relayClients.keys()),
+      ...Array.from(lifecycles.keys()),
+    ]);
+
+    const accountSnapshots = Object.fromEntries(
+      Array.from(configuredAccounts).map((accountId) => {
+        const lifecycle = lifecycles.get(accountId)?.snapshot?.() || null;
+        const relayClient = relayClients.get(accountId)?.snapshot?.() || null;
+        const runtimeContext = accountRuntimeContexts.get(accountId) || null;
+        const deferredFailure = runtimeContext?.deferredFailure || null;
+        const connected = Boolean(relayClient && relayClient.connectionState === 'authenticated');
+        const lastFailure = lifecycle?.lastStartFailure || deferredFailure || null;
+        const lastError = runtimeContext?.deferredErrorMessage || lifecycle?.lastStartError || deferredFailure?.message || null;
+        const setupBlocked = isNonRecoverableBootstrapHoldError(lastFailure);
+        const degraded = Boolean(lastError) || Boolean(relayClient && relayClient.connectionState === 'error');
+        return [accountId, {
+          configured: !setupBlocked,
+          enabled: true,
+          connected,
+          degraded,
+          hasRuntime: Boolean(runtimeContext?.runtime),
+          hasCfg: Boolean(runtimeContext?.cfg),
+          lifecycle,
+          relayClient,
+          lastError,
+          lastFailure,
+        }];
+      }),
+    );
+
+    return {
+      ok: true,
+      pluginId: 'claworld',
+      version: '0.3.0',
+      defaultAccountId: null,
+      accounts: accountSnapshots,
+      relayClients: Object.fromEntries(
+        Array.from(relayClients.entries()).map(([accountId, client]) => [accountId, client?.snapshot?.() || null]),
+      ),
+      lifecycles: Object.fromEntries(
+        Array.from(lifecycles.entries()).map(([accountId, lifecycle]) => [accountId, lifecycle.snapshot()]),
+      ),
+    };
+  }
+
+  return {
+    id: 'claworld',
+    meta: {
+      id: 'claworld',
+      label: 'Claworld',
+      selectionLabel: 'Claworld Persona Relay',
+      detailLabel: 'Claworld A2A Relay Channel',
+      docsPath: '/channels/claworld',
+      docsLabel: 'claworld',
+      blurb: 'Persona/Claworld relay channel backed by persona-backend.',
+      version: '0.3.0',
+      forceAccountBinding: true,
+    },
+    onboarding: claworldOnboardingAdapter,
+    capabilities: {
+      chatTypes: ['direct'],
+      polls: false,
+      threads: false,
+      reactions: false,
+      media: false,
+      edit: false,
+      reply: true,
+    },
+    agentPrompt: {
+      messageToolHints: () => [
+        '- Claworld targets are canonical identity handles like `alice@robin`.',
+        '- Omit `target` to keep replying inside the current A2A session when the runtime already inferred the peer.',
+        '- Use explicit targets like `user:alice@robin` when you want to open a new relay session to another remote OpenClaw agent.',
+      ],
+    },
+    reload: { configPrefixes: ['channels.claworld'] },
+    configSchema: {
+      schema: claworldChannelConfigJsonSchema,
+    },
+    config: {
+      schema: claworldChannelConfigSchema,
+      validate: validateClaworldChannelConfig,
+      listAccountIds: (cfg) => listClaworldAccountIds(cfg),
+      defaultAccountId: (cfg) => defaultClaworldAccountId(cfg),
+      inspectAccount: (cfg, accountId) => inspectClaworldChannelAccount(cfg, accountId),
+      resolveAccount: (cfg, accountId) => resolveClaworldChannelAccount(cfg, accountId),
+      resolveRuntimeConfig: (cfg, accountId) => resolveClaworldRuntimeConfig(cfg, accountId),
+      isConfigured: (account, cfg) => {
+        if (account?.configured != null) return Boolean(account.configured);
+        return inspectClaworldChannelAccount(account || cfg || {}).configured;
+      },
+      describeAccount: (account, cfg) => {
+        if (account?.configured != null) return account;
+        return inspectClaworldChannelAccount(account || cfg || {});
+      },
+    },
+    setup: claworldSetupAdapter,
+    messaging: {
+      normalizeTarget: (raw) => normalizeClaworldTarget(raw) ?? undefined,
+      targetResolver: {
+        looksLikeId: (raw, normalized) => {
+          const value = String(normalized || raw || '').trim();
+          if (!value) return false;
+          if (value.includes('@')) return RELAY_CANONICAL_AGENT_CODE_PATTERN.test(value);
+          return /^[a-z0-9._:+~-]+$/i.test(value) || /^agt_[a-z0-9_-]+$/i.test(value);
+        },
+        hint: '<agent@relay-domain|agentId>',
+      },
+    },
+    directory: {
+      self: async ({ cfg, accountId } = {}) => {
+        const account = inspectClaworldChannelAccount(cfg || {}, accountId || null);
+        const address = resolveRelayAddress(account?.accountId || '', account || {});
+        if (!account?.configured || !address) return null;
+        return {
+          id: address,
+          name: account.accountId,
+          handle: account.accountId,
+        };
+      },
+      listPeers: async ({ cfg, accountId } = {}) => buildClaworldDirectoryEntries(cfg || {}, accountId || null),
+      listGroups: async () => [],
+    },
+    status: {
+      getSnapshot: () => createStatusSnapshot(),
+    },
+    gateway: {
+      startAccount: async (context = {}) => {
+        context.log?.info?.(`starting claworld[${context.accountId || context.account?.accountId || 'default'}]`);
+        return runAccountLifecycle({
+          ...context,
+          config: context.cfg || context.config || context.account || {},
+        });
+      },
+      stopAccount: async (context = {}) => {
+        const accountKey = String(context.accountId || context.account?.accountId || 'default');
+        const lifecycle = getAccountLifecycle(accountKey);
+        return lifecycle.stop('stop_account');
+      },
+      start: (context = {}) => runAccountLifecycle(context),
+      stop: async (reasonOrContext = 'manual_stop') => {
+        if (typeof reasonOrContext === 'object' && reasonOrContext !== null) {
+          const accountKey = String(reasonOrContext.accountId || reasonOrContext.account?.accountId || 'default');
+          return getAccountLifecycle(accountKey).stop(reasonOrContext.reason || 'manual_stop');
+        }
+        const entries = Array.from(lifecycles.entries());
+        await Promise.all(entries.map(([, lifecycle]) => lifecycle.stop(reasonOrContext)));
+        return { started: false, stopped: true, reason: reasonOrContext };
+      },
+      reconnect: async (context = {}) => {
+        const accountKey = String(context.accountId || context.account?.accountId || 'default');
+        return getAccountLifecycle(accountKey).reconnect(context);
+      },
+      snapshot: () => ({
+        lifecycles: Object.fromEntries(Array.from(lifecycles.entries()).map(([accountId, lifecycle]) => [accountId, lifecycle.snapshot()])),
+        relayClients: Object.fromEntries(Array.from(relayClients.entries()).map(([accountId, client]) => [accountId, client?.snapshot?.() || null])),
+      }),
+    },
+    inbound: {
+      routeRelayEvent: (event = {}, options = {}) => {
+        const envelope = {
+          session_id: event.session_id || event.sessionId || null,
+          event_id: event.event_id || event.eventId || null,
+          from_agent_id: event.from_agent_id || event.fromAgentId || null,
+          type: event.type || 'message',
+          payload: event.payload || {},
+        };
+        return inbound.routeInboundEvent(envelope, options);
+      },
+    },
+    outbound: {
+      deliveryMode: 'direct',
+      createReplyEnvelope: (params = {}) => outbound.createReplyEnvelope(params),
+      sendText: async (ctx = {}) => {
+        if (typeof fetchImpl !== 'function') throw new Error('fetch is unavailable for claworld outbound');
+        const resolvedContext = await resolveBoundRuntimeContext(ctx);
+        return deliverRelayMessage({
+          runtimeConfig: resolvedContext.runtimeConfig,
+          to: ctx.to,
+          text: ctx.text,
+          fetchImpl,
+          logger,
+          outboundContext: ctx,
+        });
+      },
+    },
+    helpers: {
+      resolveToolRuntimeContext: resolveBoundRuntimeContext,
+      pairing: {
+        ensureAgentPairing: async (context = {}) => ensureAgentPairing({
+          runtimeConfig: context.runtimeConfig || resolveClaworldRuntimeConfig(context.cfg || {}, context.accountId || null),
+          fetchImpl,
+          logger,
+        }),
+        resolveAgentIdentity: async (context = {}) => resolveRelayAgentSummary({
+          runtimeConfig: context.runtimeConfig || resolveClaworldRuntimeConfig(context.cfg || {}, context.accountId || null),
+          fetchImpl,
+          logger,
+          agentId: context.agentId || context.targetAgentId || null,
+          agentCode: context.agentCode || context.targetAgentCode || null,
+          address: context.address || null,
+        }),
+      },
+      social: {
+        sendFriendRequest: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return createFriendRequest({
+            runtimeConfig: resolvedContext.runtimeConfig,
+            fromAgentId: resolvedContext.agentId || null,
+            toAddress: context.toAddress || null,
+            message: context.message || null,
+            metadata: context.metadata || {},
+            fetchImpl,
+          });
+        },
+        listFriendRequests: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return listFriendRequests({
+            runtimeConfig: resolvedContext.runtimeConfig,
+            agentId: resolvedContext.agentId || null,
+            direction: context.direction || null,
+            status: context.status || null,
+            fetchImpl,
+          });
+        },
+        acceptFriendRequest: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return acceptFriendRequest({
+            runtimeConfig: resolvedContext.runtimeConfig,
+            actorAgentId: resolvedContext.agentId || null,
+            friendRequestId: context.friendRequestId || null,
+            fetchImpl,
+          });
+        },
+        rejectFriendRequest: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return rejectFriendRequest({
+            runtimeConfig: resolvedContext.runtimeConfig,
+            actorAgentId: resolvedContext.agentId || null,
+            friendRequestId: context.friendRequestId || null,
+            fetchImpl,
+          });
+        },
+        requestChat: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return createChatRequest({
+            runtimeConfig: resolvedContext.runtimeConfig,
+            fromAgentId: resolvedContext.agentId || null,
+            targetAgentId: context.targetAgentId || null,
+            openingMessage: context.openingMessage || context.message || context.text || null,
+            worldId: context.worldId || null,
+            episodePolicy: context.episodePolicy || null,
+            fetchImpl,
+          });
+        },
+        listChatRequests: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return listChatRequests({
+            runtimeConfig: resolvedContext.runtimeConfig,
+            agentId: resolvedContext.agentId || null,
+            direction: context.direction || null,
+            fetchImpl,
+          });
+        },
+        acceptChatRequest: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return acceptChatRequest({
+            runtimeConfig: resolvedContext.runtimeConfig,
+            actorAgentId: resolvedContext.agentId || null,
+            chatRequestId: context.chatRequestId || null,
+            fetchImpl,
+          });
+        },
+      },
+      postSetup: {
+        fetchWorldDirectory: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return fetchPostSetupWorldDirectory({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            limit: context.limit ?? null,
+            sort: context.sort || null,
+            page: context.page ?? null,
+            fetchImpl,
+            logger,
+          });
+        },
+        fetchWorldDetail: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return fetchWorldDetail({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            worldId: context.worldId || null,
+            fetchImpl,
+            logger,
+          });
+        },
+        fetchWorldJoinCheck: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return fetchWorldJoinCheck({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            worldId: context.worldId || null,
+            profile: context.profile || {},
+            maxFieldsPerStep: context.maxFieldsPerStep ?? context.maxPromptFields ?? null,
+            fetchImpl,
+            logger,
+          });
+        },
+        joinWorld: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return joinWorld({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            worldId: context.worldId || null,
+            agentId: resolvedContext.agentId || null,
+            profile: context.profile || {},
+            profileSnapshot: context.profileSnapshot ?? null,
+            maxFieldsPerStep: context.maxFieldsPerStep ?? context.maxPromptFields ?? null,
+            fetchImpl,
+            logger,
+          });
+        },
+        submitWorldJoin: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return submitWorldJoin({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            worldId: context.worldId || null,
+            agentId: resolvedContext.agentId || null,
+            profile: context.profile || {},
+            profileSnapshot: context.profileSnapshot ?? null,
+            profileUpdate: context.profileUpdate ?? context.profilePatch ?? null,
+            maxFieldsPerStep: context.maxFieldsPerStep ?? context.maxPromptFields ?? 1,
+            fetchImpl,
+            logger,
+          });
+        },
+        fetchWorldCandidateFeed: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return fetchWorldCandidateFeed({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            worldId: context.worldId || null,
+            agentId: resolvedContext.agentId || null,
+            limit: context.limit ?? context.candidateLimit ?? null,
+            fetchImpl,
+            logger,
+          });
+        },
+        fetchWorldSearch: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return fetchWorldSearch({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            worldId: context.worldId || null,
+            agentId: resolvedContext.agentId || null,
+            query: context.query || {},
+            limit: context.limit ?? null,
+            fetchImpl,
+            logger,
+          });
+        },
+        submitWorldSearch: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return submitWorldSearch({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            worldId: context.worldId || null,
+            agentId: resolvedContext.agentId || null,
+            query: context.query || {},
+            limit: context.limit ?? null,
+            fetchImpl,
+            logger,
+          });
+        },
+        resolveWorldSelection: (context = {}) => resolveWorldSelection(
+          context.worldDirectory || {},
+          context.selection ?? context.userChoice ?? null,
+        ),
+        buildCandidateDeliverySummary,
+        buildRequiredFieldExplanation,
+        resolveWorldProfileCollectionFlow: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return resolveWorldProfileCollectionFlow({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            worldId: context.worldId || null,
+            worldDetail: context.worldDetail || null,
+            profile: context.profile || {},
+            profileUpdate: context.profileUpdate ?? context.profilePatch ?? null,
+            maxFieldsPerStep: context.maxFieldsPerStep ?? context.maxPromptFields ?? 1,
+            fetchImpl,
+            logger,
+          });
+        },
+        resolveWorldJoinFlow: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return resolveWorldJoinFlow({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            worldId: context.worldId || null,
+            worldDetail: context.worldDetail || null,
+            agentId: resolvedContext.agentId || null,
+            profile: context.profile || {},
+            profileSnapshot: context.profileSnapshot ?? null,
+            limit: context.limit ?? context.candidateLimit ?? null,
+            fetchImpl,
+            logger,
+          });
+        },
+        resolveWorldSelectionFlow: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return resolveWorldSelectionFlow({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            worldDirectory: context.worldDirectory || null,
+            selection: context.selection ?? context.userChoice ?? null,
+            profile: context.profile || {},
+            maxFieldsPerStep: context.maxFieldsPerStep ?? context.maxPromptFields ?? 1,
+            fetchImpl,
+            logger,
+          });
+        },
+      },
+      moderation: {
+        createWorld: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return createModeratedWorld({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            agentId: resolvedContext.agentId || null,
+            adminAgentIds: context.adminAgentIds || [],
+            eligibility: context.eligibility || 'active',
+            ...(Object.prototype.hasOwnProperty.call(context, 'broadcast') ? { broadcast: context.broadcast } : {}),
+            displayName: context.displayName || null,
+            summary: context.summary || null,
+            description: context.description || null,
+            entryProfileSchema: context.entryProfileSchema || {},
+            sessionTemplate: context.sessionTemplate || null,
+            interactionRules: context.interactionRules || null,
+            prohibitedRules: context.prohibitedRules || null,
+            ratingRules: context.ratingRules || null,
+            enabled: context.enabled === true,
+            fetchImpl,
+            logger,
+          });
+        },
+        listOwnedWorlds: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return fetchOwnedWorlds({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            agentId: resolvedContext.agentId || null,
+            includeDisabled: context.includeDisabled !== false,
+            fetchImpl,
+            logger,
+          });
+        },
+        manageWorld: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return manageModeratedWorld({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            agentId: resolvedContext.agentId || null,
+            worldId: context.worldId || null,
+            mode: context.mode || 'get',
+            changes: context.changes || null,
+            enabled: Object.prototype.hasOwnProperty.call(context, 'enabled') ? context.enabled : null,
+            fetchImpl,
+            logger,
+          });
+        },
+      },
+    },
+    runtime: {
+      protocol,
+      inbound,
+      outbound,
+      results,
+      demo,
+      productShell: {
+        fetchWorldDirectory: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return fetchPostSetupWorldDirectory({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            limit: context.limit ?? null,
+            sort: context.sort || null,
+            page: context.page ?? null,
+            fetchImpl,
+            logger,
+          });
+        },
+        buildWorldSelectionPrompt,
+        fetchWorldDetail: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return fetchWorldDetail({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            worldId: context.worldId || null,
+            fetchImpl,
+            logger,
+          });
+        },
+        fetchWorldJoinCheck: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return fetchWorldJoinCheck({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            worldId: context.worldId || null,
+            profile: context.profile || {},
+            maxFieldsPerStep: context.maxFieldsPerStep ?? context.maxPromptFields ?? null,
+            fetchImpl,
+            logger,
+          });
+        },
+        joinWorld: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return joinWorld({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            worldId: context.worldId || null,
+            agentId: resolvedContext.agentId || null,
+            profile: context.profile || {},
+            profileSnapshot: context.profileSnapshot ?? null,
+            maxFieldsPerStep: context.maxFieldsPerStep ?? context.maxPromptFields ?? null,
+            fetchImpl,
+            logger,
+          });
+        },
+        submitWorldJoin: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return submitWorldJoin({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            worldId: context.worldId || null,
+            agentId: resolvedContext.agentId || null,
+            profile: context.profile || {},
+            profileSnapshot: context.profileSnapshot ?? null,
+            profileUpdate: context.profileUpdate ?? context.profilePatch ?? null,
+            maxFieldsPerStep: context.maxFieldsPerStep ?? context.maxPromptFields ?? 1,
+            fetchImpl,
+            logger,
+          });
+        },
+        fetchWorldCandidateFeed: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return fetchWorldCandidateFeed({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            worldId: context.worldId || null,
+            agentId: resolvedContext.agentId || null,
+            limit: context.limit ?? context.candidateLimit ?? null,
+            fetchImpl,
+            logger,
+          });
+        },
+        fetchWorldSearch: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return fetchWorldSearch({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            worldId: context.worldId || null,
+            agentId: resolvedContext.agentId || null,
+            query: context.query || {},
+            limit: context.limit ?? null,
+            fetchImpl,
+            logger,
+          });
+        },
+        submitWorldSearch: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return submitWorldSearch({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            worldId: context.worldId || null,
+            agentId: resolvedContext.agentId || null,
+            query: context.query || {},
+            limit: context.limit ?? null,
+            fetchImpl,
+            logger,
+          });
+        },
+        broadcastWorld: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return broadcastWorld({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            worldId: context.worldId || null,
+            agentId: resolvedContext.agentId || null,
+            message: context.message || null,
+            payload: context.payload || {},
+            audience: context.audience || null,
+            replyPolicy: context.replyPolicy || null,
+            ...(Object.prototype.hasOwnProperty.call(context, 'excludeSelf') ? { excludeSelf: context.excludeSelf } : {}),
+            conversation: context.conversation || {},
+            fetchImpl,
+            logger,
+          });
+        },
+        resolveWorldSelection,
+        buildCandidateDeliverySummary,
+        buildRequiredFieldExplanation,
+        resolveWorldProfileCollectionFlow: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return resolveWorldProfileCollectionFlow({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            worldId: context.worldId || null,
+            worldDetail: context.worldDetail || null,
+            profile: context.profile || {},
+            profileUpdate: context.profileUpdate ?? context.profilePatch ?? null,
+            maxFieldsPerStep: context.maxFieldsPerStep ?? context.maxPromptFields ?? 1,
+            fetchImpl,
+            logger,
+          });
+        },
+        resolveWorldJoinFlow: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return resolveWorldJoinFlow({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            worldId: context.worldId || null,
+            worldDetail: context.worldDetail || null,
+            agentId: resolvedContext.agentId || null,
+            profile: context.profile || {},
+            profileSnapshot: context.profileSnapshot ?? null,
+            limit: context.limit ?? context.candidateLimit ?? null,
+            fetchImpl,
+            logger,
+          });
+        },
+        resolveWorldSelectionFlow: async (context = {}) => {
+          const resolvedContext = await resolveBoundRuntimeContext(context);
+          return resolveWorldSelectionFlow({
+            cfg: resolvedContext.cfg || {},
+            accountId: resolvedContext.accountId || null,
+            runtimeConfig: resolvedContext.runtimeConfig || null,
+            worldDirectory: context.worldDirectory || null,
+            selection: context.selection ?? context.userChoice ?? null,
+            profile: context.profile || {},
+            maxFieldsPerStep: context.maxFieldsPerStep ?? context.maxPromptFields ?? 1,
+            fetchImpl,
+            logger,
+          });
+        },
+        feedback: {
+          submitFeedback: async (context = {}) => {
+            const resolvedContext = await resolveBoundRuntimeContext(context);
+            return submitFeedbackReport({
+              cfg: resolvedContext.cfg || {},
+              accountId: resolvedContext.accountId || null,
+              runtimeConfig: resolvedContext.runtimeConfig || null,
+              agentId: resolvedContext.agentId || null,
+              category: context.category || null,
+              title: context.title || null,
+              goal: context.goal || null,
+              actualBehavior: context.actualBehavior || null,
+              expectedBehavior: context.expectedBehavior || null,
+              impact: context.impact || null,
+              details: context.details || null,
+              reproductionSteps: context.reproductionSteps || [],
+              context: context.context || {},
+              fetchImpl,
+              logger,
+              toolCallId: context.toolCallId || null,
+              pluginVersion: context.pluginVersion || null,
+              toolContractVersion: context.toolContractVersion || null,
+            });
+          },
+        },
+        moderation: {
+          createWorld: async (context = {}) => {
+            const resolvedContext = await resolveBoundRuntimeContext(context);
+            return createModeratedWorld({
+              cfg: resolvedContext.cfg || {},
+              accountId: resolvedContext.accountId || null,
+              runtimeConfig: resolvedContext.runtimeConfig || null,
+              agentId: resolvedContext.agentId || null,
+              adminAgentIds: context.adminAgentIds || [],
+              eligibility: context.eligibility || 'active',
+              ...(Object.prototype.hasOwnProperty.call(context, 'broadcast') ? { broadcast: context.broadcast } : {}),
+              displayName: context.displayName || null,
+              summary: context.summary || null,
+            description: context.description || null,
+            entryProfileSchema: context.entryProfileSchema || {},
+            sessionTemplate: context.sessionTemplate || null,
+            interactionRules: context.interactionRules || null,
+            prohibitedRules: context.prohibitedRules || null,
+            ratingRules: context.ratingRules || null,
+            enabled: context.enabled === true,
+              fetchImpl,
+              logger,
+            });
+          },
+          listOwnedWorlds: async (context = {}) => {
+            const resolvedContext = await resolveBoundRuntimeContext(context);
+            return fetchOwnedWorlds({
+              cfg: resolvedContext.cfg || {},
+              accountId: resolvedContext.accountId || null,
+              runtimeConfig: resolvedContext.runtimeConfig || null,
+              agentId: resolvedContext.agentId || null,
+              includeDisabled: context.includeDisabled !== false,
+              fetchImpl,
+              logger,
+            });
+          },
+          manageWorld: async (context = {}) => {
+            const resolvedContext = await resolveBoundRuntimeContext(context);
+            return manageModeratedWorld({
+              cfg: resolvedContext.cfg || {},
+              accountId: resolvedContext.accountId || null,
+              runtimeConfig: resolvedContext.runtimeConfig || null,
+              agentId: resolvedContext.agentId || null,
+              worldId: context.worldId || null,
+              mode: context.mode || 'get',
+              changes: context.changes || null,
+              enabled: Object.prototype.hasOwnProperty.call(context, 'enabled') ? context.enabled : null,
+              fetchImpl,
+              logger,
+            });
+          },
+        },
+      },
+      createRelayClient: (options = {}) => relayClientFactory({ logger, inbound, outbound, protocol, ...options }),
+    },
+    internals: {
+      protocol,
+      inbound,
+      outbound,
+      results,
+      demo,
+      lifecycles,
+      getRelayClient: (accountId = 'default') => relayClients.get(accountId) || null,
+    },
+    async start(context = {}) {
+      return runAccountLifecycle(context);
+    },
+    async stop(reason) {
+      return this.gateway.stop(reason);
+    },
+    async reconnect(context = {}) {
+      return this.gateway.reconnect(context);
+    },
+    describe() {
+      return {
+        id: this.id,
+        meta: this.meta,
+        capabilities: this.capabilities,
+        configSchema: this.configSchema,
+        runtimePath: inbound.runtimePath,
+        lifecycle: this.gateway.snapshot(),
+        relayClient: relayClients.get('default')?.snapshot?.() || null,
+        status: createStatusSnapshot(),
+        readyFor: [
+          'plugin manifest validation',
+          'config inspection',
+          'native channel setup/onboarding',
+          'relay websocket adapter tests',
+          'manual relay-agent binding',
+          'minimal outbound session-request send',
+        ],
+        notImplemented: [
+          '真实 OpenClaw sdk import/types 对齐',
+          'ack/retry persistence',
+          'console + demo wiring',
+        ],
+      };
+    },
+  };
+}
+
+export const claworldChannelPluginScaffold = createClaworldChannelPlugin;
+export { normalizeRelayHttpBaseUrl };