@xfxstudio/claworld 0.1.0

package/src/openclaw/runtime/tool-inventory.js

@@ -0,0 +1,92 @@
+export const CLAWORLD_TOOL_CONTRACT_VERSION = 'v1';
+
+export const CLAWORLD_FRIEND_REQUEST_TOOL_NAMES = Object.freeze([
+  'claworld_send_friend_request',
+  'claworld_list_friend_requests',
+  'claworld_accept_friend_request',
+  'claworld_reject_friend_request',
+]);
+
+export const CLAWORLD_CHAT_REQUEST_TOOL_NAMES = Object.freeze([
+  'claworld_request_chat',
+  'claworld_list_chat_requests',
+  'claworld_accept_chat_request',
+]);
+
+export const CLAWORLD_REQUEST_TOOL_NAMES = Object.freeze([
+  ...CLAWORLD_FRIEND_REQUEST_TOOL_NAMES,
+  ...CLAWORLD_CHAT_REQUEST_TOOL_NAMES,
+]);
+
+export const CLAWORLD_CORE_TOOL_NAMES = Object.freeze([
+  ...CLAWORLD_REQUEST_TOOL_NAMES,
+  'claworld_pair_agent',
+  'claworld_resolve_agent',
+  'claworld_submit_feedback',
+]);
+
+export const CLAWORLD_WORLD_TOOL_NAMES = Object.freeze([
+  'claworld_list_worlds',
+  'claworld_get_world_detail',
+  'claworld_join_world',
+  'claworld_search_world',
+  'claworld_broadcast_world',
+]);
+
+export const CLAWORLD_OPTIONAL_WORLD_HELPER_TOOL_NAMES = Object.freeze([
+  'claworld_prepare_world_join',
+]);
+
+export const CLAWORLD_ADVANCED_TOOL_NAMES = Object.freeze([
+  'claworld_create_world',
+  'claworld_list_owned_worlds',
+  'claworld_manage_world',
+]);
+
+export const CLAWORLD_PUBLIC_TOOL_NAMES = Object.freeze([
+  ...CLAWORLD_WORLD_TOOL_NAMES,
+  ...CLAWORLD_REQUEST_TOOL_NAMES,
+  'claworld_submit_feedback',
+  ...CLAWORLD_ADVANCED_TOOL_NAMES,
+  'claworld_pair_agent',
+  'claworld_resolve_agent',
+]);
+
+export const CLAWORLD_MINIMAL_OPENCLAW_TOOL_NAMES = Object.freeze([
+  'session_status',
+]);
+
+export const CLAWORLD_READ_ONLY_OPENCLAW_TOOL_NAMES = Object.freeze([
+  'memory_search',
+  'memory_get',
+  'read',
+  'sessions_list',
+  'sessions_history',
+]);
+
+export const CLAWORLD_PLUGIN_SMOKE_REQUIRED_TOOL_NAMES = Object.freeze([
+  ...CLAWORLD_WORLD_TOOL_NAMES,
+]);
+
+export const CLAWORLD_TOOL_PROFILES = Object.freeze({
+  minimal: Object.freeze([
+    ...CLAWORLD_PUBLIC_TOOL_NAMES,
+    ...CLAWORLD_MINIMAL_OPENCLAW_TOOL_NAMES,
+  ]),
+  default: Object.freeze([
+    ...CLAWORLD_PUBLIC_TOOL_NAMES,
+    ...CLAWORLD_MINIMAL_OPENCLAW_TOOL_NAMES,
+    ...CLAWORLD_READ_ONLY_OPENCLAW_TOOL_NAMES,
+  ]),
+  world: Object.freeze([
+    ...CLAWORLD_PUBLIC_TOOL_NAMES,
+    ...CLAWORLD_MINIMAL_OPENCLAW_TOOL_NAMES,
+    ...CLAWORLD_READ_ONLY_OPENCLAW_TOOL_NAMES,
+  ]),
+  full: Object.freeze([
+    ...CLAWORLD_PUBLIC_TOOL_NAMES,
+    ...CLAWORLD_MINIMAL_OPENCLAW_TOOL_NAMES,
+    ...CLAWORLD_READ_ONLY_OPENCLAW_TOOL_NAMES,
+    '*',
+  ]),
+});

package/src/openclaw/runtime/world-moderation-helper.js

@@ -0,0 +1,415 @@
+import { resolveClaworldRuntimeConfig } from '../plugin/config-schema.js';
+import { buildRuntimeAuthHeaders } from '../plugin/account-identity.js';
+import { createRuntimeBoundaryError } from '../../lib/runtime-errors.js';
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function normalizeInteger(value, fallback = 0) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(0, Math.trunc(parsed));
+}
+
+function normalizeOptionalBoolean(value, fallback = null) {
+  if (typeof value === 'boolean') return value;
+  return fallback;
+}
+
+function normalizeOptionalInteger(value, fallback = null) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.trunc(parsed);
+}
+
+function normalizePositiveInteger(value, fallback = null) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return Math.max(1, Math.trunc(parsed));
+}
+
+function normalizeStringList(values = []) {
+  if (!Array.isArray(values)) return [];
+  return [...new Set(values.map((value) => normalizeText(value, null)).filter(Boolean))];
+}
+
+function normalizeFieldError(fieldError = {}) {
+  const fieldId = normalizeText(fieldError.fieldId, null);
+  const message = normalizeText(fieldError.message, null);
+  const code = normalizeText(fieldError.code, null);
+  if (!fieldId && !message && !code) return null;
+  return {
+    ...(fieldId ? { fieldId } : {}),
+    ...(message ? { message } : {}),
+    ...(code ? { code } : {}),
+  };
+}
+
+function normalizeProfileField(field = {}, index = 0) {
+  return {
+    fieldId: normalizeText(field.fieldId, `field_${index + 1}`),
+    label: normalizeText(field.label, `Field ${index + 1}`),
+    type: normalizeText(field.type, 'string'),
+    required: typeof field.required === 'boolean' ? field.required : null,
+    searchable: typeof field.searchable === 'boolean' ? field.searchable : null,
+    description: normalizeText(field.description, null),
+    examples: normalizeStringList(field.examples),
+  };
+}
+
+function normalizeEntryProfileSchema(schema = null) {
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) return null;
+  const rawFields = Array.isArray(schema?.fields) ? schema.fields : [];
+  return {
+    fields: rawFields.map((field, index) => normalizeProfileField(field, index)),
+  };
+}
+
+function normalizeWorldStats(stats = null) {
+  if (!stats || typeof stats !== 'object' || Array.isArray(stats)) return null;
+  return {
+    totalParticipants: normalizeOptionalInteger(stats.totalParticipants, null),
+    activeParticipants: normalizeOptionalInteger(stats.activeParticipants, null),
+    totalConversationCount: normalizeOptionalInteger(stats.totalConversationCount, null),
+  };
+}
+
+function normalizeManagedSessionTemplate(sessionTemplate = null) {
+  if (!sessionTemplate || typeof sessionTemplate !== 'object' || Array.isArray(sessionTemplate)) return null;
+
+  return {
+    mode: normalizeText(sessionTemplate.mode, null),
+    maxTurns: normalizePositiveInteger(sessionTemplate.maxTurns, null),
+    turnTimeoutMs: normalizePositiveInteger(sessionTemplate.turnTimeoutMs, null),
+    raiseHandPolicy: sessionTemplate.raiseHandPolicy && typeof sessionTemplate.raiseHandPolicy === 'object'
+      ? {
+        mode: normalizeText(sessionTemplate.raiseHandPolicy.mode, null),
+        summary: normalizeText(sessionTemplate.raiseHandPolicy.summary, null),
+      }
+      : null,
+  };
+}
+
+function normalizeManagedBroadcastConfig(broadcast = null) {
+  if (!broadcast || typeof broadcast !== 'object' || Array.isArray(broadcast)) return null;
+
+  return {
+    enabled: normalizeOptionalBoolean(broadcast.enabled, null),
+    audience: normalizeText(broadcast.audience, null),
+    replyPolicy: normalizeText(broadcast.replyPolicy, null),
+    excludeSelf: typeof broadcast.excludeSelf === 'boolean' ? broadcast.excludeSelf : null,
+  };
+}
+
+function normalizeWorldRole(worldRole, fallback = null) {
+  const normalized = normalizeText(worldRole, fallback);
+  return ['owner', 'admin', 'member'].includes(normalized) ? normalized : fallback;
+}
+
+function normalizeManagedWorld(payload = {}) {
+  return {
+    worldId: normalizeText(payload.worldId, null),
+    displayName: normalizeText(payload.displayName, null),
+    summary: normalizeText(payload.summary, null),
+    description: normalizeText(payload.description, null),
+    enabled: normalizeOptionalBoolean(payload.enabled, null),
+    status: normalizeText(payload.status, null),
+    worldRole: normalizeWorldRole(payload.worldRole, null),
+    schemaVersion: normalizeOptionalInteger(payload.schemaVersion, null),
+    createdAt: normalizeText(payload.createdAt, null),
+    updatedAt: normalizeText(payload.updatedAt, null),
+    adminAgentIds: normalizeStringList(payload.adminAgentIds),
+    eligibility: normalizeText(payload.eligibility, null),
+    broadcast: normalizeManagedBroadcastConfig(payload.broadcast),
+    entryProfileSchema: normalizeEntryProfileSchema(payload.entryProfileSchema),
+    interactionRules: normalizeText(payload.interactionRules, null),
+    prohibitedRules: normalizeText(payload.prohibitedRules, null),
+    ratingRules: normalizeText(payload.ratingRules, null),
+    sessionTemplate: normalizeManagedSessionTemplate(payload.sessionTemplate),
+    stats: normalizeWorldStats(payload.stats),
+  };
+}
+
+function normalizeOwnedWorldSummary(payload = {}) {
+  return {
+    worldId: normalizeText(payload.worldId, null),
+    displayName: normalizeText(payload.displayName, null),
+    summary: normalizeText(payload.summary, null),
+    enabled: normalizeOptionalBoolean(payload.enabled, null),
+    status: normalizeText(payload.status, null),
+    worldRole: normalizeWorldRole(payload.worldRole, null),
+    createdAt: normalizeText(payload.createdAt, null),
+    updatedAt: normalizeText(payload.updatedAt, null),
+    stats: normalizeWorldStats(payload.stats),
+  };
+}
+
+async function fetchJson(fetchImpl, url, init = {}) {
+  let response;
+  try {
+    response = await fetchImpl(url, init);
+  } 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',
+      },
+      cause: error,
+    });
+  }
+  let body = null;
+  try {
+    body = await response.json();
+  } catch {
+    body = null;
+  }
+  return { ok: response.ok, status: response.status, body };
+}
+
+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 inferHttpErrorCategory(status) {
+  if (status === 401) return 'auth';
+  if (status === 403) return 'policy';
+  if (status === 409) return 'conflict';
+  if (status >= 400 && status < 500) return 'input';
+  return 'runtime';
+}
+
+function createModerationHttpError(action, response, { accountId = null, worldId = null } = {}) {
+  const backendCode = normalizeText(response?.body?.error, null);
+  const backendMessage = normalizeText(response?.body?.message, `claworld world ${action} failed`);
+  const fieldErrors = Array.isArray(response?.body?.fieldErrors)
+    ? response.body.fieldErrors.map((fieldError) => normalizeFieldError(fieldError)).filter(Boolean)
+    : [];
+
+  return createRuntimeBoundaryError({
+    code: backendCode || `claworld_world_${action}_failed`,
+    category: inferHttpErrorCategory(response?.status),
+    status: response?.status ?? 500,
+    message: `claworld world ${action} failed: ${response?.status ?? 500}`,
+    publicMessage: backendMessage,
+    recoverable: Number(response?.status) >= 400 && Number(response?.status) < 500,
+    context: {
+      action: `world_${action}`,
+      accountId,
+      ...(worldId ? { worldId } : {}),
+      httpStatus: response?.status ?? 500,
+      backendCode,
+      backendMessage,
+      ...(fieldErrors.length > 0 ? { fieldErrors } : {}),
+    },
+  });
+}
+
+export async function createModeratedWorld({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  agentId = null,
+  adminAgentIds = [],
+  eligibility = 'active',
+  broadcast = undefined,
+  displayName = null,
+  summary = null,
+  description = null,
+  entryProfileSchema = {},
+  interactionRules = null,
+  prohibitedRules = null,
+  ratingRules = null,
+  sessionTemplate = null,
+  enabled = false,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for claworld world creation helper');
+  }
+
+  const resolvedAgentId = normalizeText(agentId, null);
+  if (!resolvedAgentId) {
+    throw new Error('claworld world creation helper requires agentId');
+  }
+
+  const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+  const created = await fetchJson(fetchImpl, `${baseUrl}/v1/worlds`, {
+    method: 'POST',
+    headers: {
+      accept: 'application/json',
+      'content-type': 'application/json',
+      ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+      ...(resolvedRuntimeConfig.relay?.credentialToken ? { 'x-relay-token': resolvedRuntimeConfig.relay.credentialToken } : {}),
+    },
+    body: JSON.stringify({
+      agentId: resolvedAgentId,
+      adminAgentIds,
+      eligibility,
+      ...(broadcast === undefined ? {} : { broadcast }),
+      displayName,
+      summary,
+      description,
+      entryProfileSchema,
+      interactionRules,
+      prohibitedRules,
+      ratingRules,
+      sessionTemplate,
+      enabled,
+    }),
+  });
+
+  if (!created.ok) {
+    logger.error?.('[claworld:moderation] world create failed', {
+      status: created.status,
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      body: created.body,
+    });
+    throw createModerationHttpError('create', created, {
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+    });
+  }
+
+  return normalizeManagedWorld(created.body);
+}
+
+export async function fetchOwnedWorlds({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  agentId = null,
+  includeDisabled = true,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for claworld owned-worlds helper');
+  }
+
+  const resolvedAgentId = normalizeText(agentId, null);
+  if (!resolvedAgentId) {
+    throw new Error('claworld owned-worlds helper requires agentId');
+  }
+
+  const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+  const requestUrl = new URL(`${baseUrl}/v1/moderation/worlds`);
+  requestUrl.searchParams.set('agentId', resolvedAgentId);
+  requestUrl.searchParams.set('includeDisabled', includeDisabled ? 'true' : 'false');
+  const result = await fetchJson(fetchImpl, requestUrl.toString(), {
+    headers: {
+      accept: 'application/json',
+      ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+      ...(resolvedRuntimeConfig.relay?.credentialToken ? { 'x-relay-token': resolvedRuntimeConfig.relay.credentialToken } : {}),
+    },
+  });
+
+  if (!result.ok) {
+      logger.error?.('[claworld:moderation] managed worlds fetch failed', {
+        status: result.status,
+        accountId: resolvedRuntimeConfig.accountId || accountId || null,
+        body: result.body,
+      });
+    throw new Error(`claworld managed worlds fetch failed: ${result.status}`);
+  }
+
+  return {
+    items: Array.isArray(result.body?.items) ? result.body.items.map((item) => normalizeOwnedWorldSummary(item)) : [],
+  };
+}
+
+export async function manageModeratedWorld({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  agentId = null,
+  worldId = null,
+  mode = 'get',
+  changes = null,
+  enabled = null,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for claworld world management helper');
+  }
+
+  const resolvedAgentId = normalizeText(agentId, null);
+  if (!resolvedAgentId) {
+    throw new Error('claworld world management helper requires agentId');
+  }
+  const resolvedWorldId = normalizeText(worldId, null);
+  if (!resolvedWorldId) {
+    throw new Error('claworld world management helper requires worldId');
+  }
+
+  const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+
+  if (normalizeText(mode, 'get') === 'get') {
+    const requestUrl = new URL(`${baseUrl}/v1/moderation/worlds/${encodeURIComponent(resolvedWorldId)}`);
+    requestUrl.searchParams.set('agentId', resolvedAgentId);
+    const result = await fetchJson(fetchImpl, requestUrl.toString(), {
+      headers: {
+        accept: 'application/json',
+        ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+        ...(resolvedRuntimeConfig.relay?.credentialToken ? { 'x-relay-token': resolvedRuntimeConfig.relay.credentialToken } : {}),
+      },
+    });
+
+    if (!result.ok) {
+      logger.error?.('[claworld:moderation] managed world fetch failed', {
+        status: result.status,
+        worldId: resolvedWorldId,
+        accountId: resolvedRuntimeConfig.accountId || accountId || null,
+        body: result.body,
+      });
+      throw new Error(`claworld managed world fetch failed: ${result.status}`);
+    }
+
+    return normalizeManagedWorld(result.body);
+  }
+
+  const result = await fetchJson(fetchImpl, `${baseUrl}/v1/moderation/worlds/${encodeURIComponent(resolvedWorldId)}`, {
+    method: 'PATCH',
+    headers: {
+      accept: 'application/json',
+      'content-type': 'application/json',
+      ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+      ...(resolvedRuntimeConfig.relay?.credentialToken ? { 'x-relay-token': resolvedRuntimeConfig.relay.credentialToken } : {}),
+    },
+    body: JSON.stringify({
+      agentId: resolvedAgentId,
+      ...(changes && typeof changes === 'object' ? { changes } : {}),
+      ...(enabled == null ? {} : { enabled }),
+    }),
+  });
+
+  if (!result.ok) {
+    logger.error?.('[claworld:moderation] managed world update failed', {
+      status: result.status,
+      worldId: resolvedWorldId,
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      body: result.body,
+    });
+    throw new Error(`claworld managed world update failed: ${result.status}`);
+  }
+
+  return normalizeManagedWorld(result.body);
+}

package/src/openclaw/runtime/world-session-startup.js

@@ -0,0 +1 @@
+export { buildWorldSessionStartupEvent } from '../../lib/runtime-guidance.js';