@xfxstudio/claworld 0.1.0

package/src/product-shell/worlds/world-authorization.js

@@ -0,0 +1,135 @@
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+export const WORLD_ROLES = Object.freeze({
+  OWNER: 'owner',
+  ADMIN: 'admin',
+  MEMBER: 'member',
+  NONE: 'none',
+});
+
+export const WORLD_ACTIONS = Object.freeze({
+  VIEW_MANAGEMENT: 'view_world_management',
+  MANAGE_WORLD: 'manage_world',
+  MANAGE_WORLD_ROLES: 'manage_world_roles',
+  CHANGE_ENABLED_STATE: 'change_world_enabled_state',
+  BROADCAST: 'broadcast_world',
+  SEARCH: 'search_world',
+  VIEW_CANDIDATE_FEED: 'view_world_candidate_feed',
+  CREATE_CHAT_REQUEST: 'create_world_chat_request',
+});
+
+function resolveWorldRole({ isOwner = false, isAdmin = false, isMember = false } = {}) {
+  if (isOwner) return WORLD_ROLES.OWNER;
+  if (isAdmin) return WORLD_ROLES.ADMIN;
+  if (isMember) return WORLD_ROLES.MEMBER;
+  return WORLD_ROLES.NONE;
+}
+
+function resolveActionRequirement(action) {
+  switch (action) {
+    case WORLD_ACTIONS.VIEW_MANAGEMENT:
+    case WORLD_ACTIONS.MANAGE_WORLD:
+    case WORLD_ACTIONS.BROADCAST:
+      return {
+        allowedRoles: [WORLD_ROLES.OWNER, WORLD_ROLES.ADMIN],
+        reason: 'management_role_required',
+      };
+    case WORLD_ACTIONS.MANAGE_WORLD_ROLES:
+    case WORLD_ACTIONS.CHANGE_ENABLED_STATE:
+      return {
+        allowedRoles: [WORLD_ROLES.OWNER],
+        reason: 'owner_role_required',
+      };
+    case WORLD_ACTIONS.SEARCH:
+    case WORLD_ACTIONS.VIEW_CANDIDATE_FEED:
+    case WORLD_ACTIONS.CREATE_CHAT_REQUEST:
+      return {
+        allowedRoles: [WORLD_ROLES.MEMBER],
+        reason: 'active_membership_required',
+        requiredMembershipStatus: 'active',
+      };
+    default:
+      return {
+        allowedRoles: [],
+        reason: 'unknown_action',
+      };
+  }
+}
+
+export function createWorldAuthorizationService({ worldService, membershipService } = {}) {
+  function resolveMembership(worldId, agentId, { includeDisabled = false } = {}) {
+    const normalizedAgentId = normalizeText(agentId, null);
+    if (!normalizedAgentId || !membershipService || typeof membershipService.getMembership !== 'function') {
+      return null;
+    }
+    return membershipService.getMembership({
+      worldId,
+      agentId: normalizedAgentId,
+      includeDisabled,
+    });
+  }
+
+  function resolveWorldActorContextForWorld(world, actorAgentId, { includeDisabled = false } = {}) {
+    const normalizedActorAgentId = normalizeText(actorAgentId, null);
+    const membership = normalizedActorAgentId
+      ? resolveMembership(world.worldId, normalizedActorAgentId, { includeDisabled })
+      : null;
+    const isOwner = normalizedActorAgentId != null && normalizedActorAgentId === world.creatorAgentId;
+    const isAdmin = normalizedActorAgentId != null
+      && Array.isArray(world.adminAgentIds)
+      && world.adminAgentIds.includes(normalizedActorAgentId);
+    const isMember = membership?.status === 'active';
+    const worldRole = resolveWorldRole({ isOwner, isAdmin, isMember });
+
+    return {
+      world,
+      actorAgentId: normalizedActorAgentId,
+      worldRole,
+      managementRole: isOwner ? WORLD_ROLES.OWNER : isAdmin ? WORLD_ROLES.ADMIN : null,
+      membership,
+      membershipStatus: membership?.status || null,
+      roles: {
+        owner: isOwner,
+        admin: isAdmin,
+        member: isMember,
+      },
+    };
+  }
+
+  return {
+    resolveWorldActorContext({ worldId, actorAgentId, includeDisabled = false } = {}) {
+      const world = worldService.requireWorld(worldId, { includeDisabled });
+      return resolveWorldActorContextForWorld(world, actorAgentId, { includeDisabled });
+    },
+
+    evaluateWorldAction({ worldId, actorAgentId, action, includeDisabled = false } = {}) {
+      const actor = this.resolveWorldActorContext({
+        worldId,
+        actorAgentId,
+        includeDisabled,
+      });
+      const requirement = resolveActionRequirement(action);
+      const allowed = requirement.allowedRoles.includes(actor.worldRole);
+
+      return {
+        ...actor,
+        action,
+        allowed,
+        allowedRoles: requirement.allowedRoles,
+        requiredMembershipStatus: requirement.requiredMembershipStatus || null,
+        reason: allowed ? 'authorized' : requirement.reason,
+      };
+    },
+
+    listManagedWorlds({ actorAgentId, includeDisabled = true } = {}) {
+      return worldService
+        .listCustomWorlds({ includeDisabled })
+        .map((world) => resolveWorldActorContextForWorld(world, actorAgentId, { includeDisabled }))
+        .filter((context) => context.managementRole != null);
+    },
+  };
+}

package/src/product-shell/worlds/world-broadcast-service.js

@@ -0,0 +1,299 @@
+import { v4 as uuidv4 } from 'uuid';
+import { WORLD_ACTIONS } from './world-authorization.js';
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function cloneJsonObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  try {
+    const cloned = JSON.parse(JSON.stringify(value));
+    if (!cloned || typeof cloned !== 'object' || Array.isArray(cloned)) return null;
+    return cloned;
+  } catch {
+    return null;
+  }
+}
+
+function normalizeBoolean(value, fallback = null) {
+  if (typeof value === 'boolean') return value;
+  return fallback;
+}
+
+function normalizeWorldEligibility(value, fallback = 'active') {
+  const normalized = normalizeText(value, fallback);
+  if (normalized === 'joined') return 'joined';
+  return 'active';
+}
+
+function normalizeBroadcastAudience(value, fallback = 'members') {
+  const normalized = normalizeText(value, fallback);
+  if (normalized === 'admins') return 'admins';
+  if (normalized === 'admins_and_owner') return 'admins_and_owner';
+  return 'members';
+}
+
+function createBroadcastId() {
+  return `brd_${uuidv4()}`;
+}
+
+function createConfigurationError() {
+  const error = new Error('world_broadcast_unavailable');
+  error.code = 'world_broadcast_unavailable';
+  error.status = 500;
+  return error;
+}
+
+function createInvalidBroadcastRequestError(fieldId, message = `${fieldId} is required`) {
+  const error = new Error(`invalid_broadcast_request:${fieldId}`);
+  error.code = 'invalid_broadcast_request';
+  error.status = 400;
+  error.responseBody = {
+    error: error.code,
+    message: 'broadcast request is invalid',
+    fieldErrors: [
+      {
+        fieldId,
+        message,
+      },
+    ],
+  };
+  return error;
+}
+
+function createBroadcastDisabledError(worldId) {
+  const error = new Error(`broadcast_disabled:${worldId}`);
+  error.code = 'broadcast_disabled';
+  error.status = 403;
+  error.responseBody = {
+    error: error.code,
+    message: 'broadcast is not enabled for this world',
+    worldId,
+  };
+  return error;
+}
+
+function createBroadcastNotAllowedError({ worldId, senderAgentId, senderRole } = {}) {
+  const error = new Error(`broadcast_not_allowed:${worldId}:${senderAgentId}`);
+  error.code = 'broadcast_not_allowed';
+  error.status = 403;
+  error.responseBody = {
+    error: error.code,
+    message: 'sender does not have permission to broadcast in this world',
+    worldId,
+    senderAgentId,
+    senderRole,
+    allowedRoles: ['owner', 'admin'],
+  };
+  return error;
+}
+
+function resolveMemberStatuses(world = {}) {
+  const eligibility = normalizeWorldEligibility(world.eligibility, 'active');
+  return eligibility === 'joined' ? new Set(['joined', 'active']) : new Set(['active']);
+}
+
+function dedupeAgentIds(agentIds = [], { excludeAgentId = null } = {}) {
+  const seen = new Set();
+  const items = [];
+  for (const rawAgentId of agentIds) {
+    const agentId = normalizeText(rawAgentId, null);
+    if (!agentId || seen.has(agentId)) continue;
+    if (excludeAgentId && agentId === excludeAgentId) continue;
+    seen.add(agentId);
+    items.push(agentId);
+  }
+  return items;
+}
+
+function normalizeBroadcastCreationError(error, { agentId = null } = {}) {
+  const responseBody = error?.responseBody && typeof error.responseBody === 'object'
+    ? error.responseBody
+    : null;
+  return {
+    agentId,
+    status: 'failed',
+    httpStatus: Number.isInteger(error?.status) ? error.status : 500,
+    error: normalizeText(responseBody?.error, normalizeText(error?.code, 'chat_request_create_failed')),
+    reason: normalizeText(responseBody?.reason, null),
+    message: normalizeText(responseBody?.message, normalizeText(error?.message, null)),
+  };
+}
+
+export function createWorldBroadcastService({
+  worldService,
+  worldAuthorizationService,
+  membershipService,
+  chatRequestService = null,
+  store = null,
+} = {}) {
+  function assertRuntime() {
+    if (!worldService || !membershipService || !chatRequestService || !store || typeof chatRequestService.createChatRequest !== 'function') {
+      throw createConfigurationError();
+    }
+  }
+
+  function resolveAudienceAgentIds(world, { audience, excludeSelf, senderAgentId } = {}) {
+    if (audience === 'admins' || audience === 'admins_and_owner') {
+      return dedupeAgentIds([
+        world.creatorAgentId,
+        ...(Array.isArray(world.adminAgentIds) ? world.adminAgentIds : []),
+      ], {
+        excludeAgentId: excludeSelf ? senderAgentId : null,
+      });
+    }
+
+    const memberStatuses = resolveMemberStatuses(world);
+    const memberAgentIds = membershipService
+      .listMemberships({ worldId: world.worldId })
+      .filter((membership) => memberStatuses.has(membership.status))
+      .map((membership) => membership.agentId);
+
+    return dedupeAgentIds(memberAgentIds, {
+      excludeAgentId: excludeSelf ? senderAgentId : null,
+    });
+  }
+
+  return {
+    async broadcastWorld({
+      worldId,
+      senderAgentId,
+      payload,
+      audience = null,
+      excludeSelf = null,
+    } = {}) {
+      assertRuntime();
+      const world = worldService.requireWorld(worldId);
+      const sender = store.getAgent(senderAgentId);
+
+      if (!sender) {
+        throw createInvalidBroadcastRequestError('agentId', 'agentId is required');
+      }
+      if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+        throw createInvalidBroadcastRequestError('payload', 'payload must be an object');
+      }
+      const openingMessage = normalizeText(payload.text, null);
+      if (!openingMessage) {
+        throw createInvalidBroadcastRequestError('payload.text', 'payload.text is required');
+      }
+
+      const worldBroadcast = world.broadcast && typeof world.broadcast === 'object'
+        ? world.broadcast
+        : {};
+      if (worldBroadcast.enabled !== true) {
+        throw createBroadcastDisabledError(world.worldId);
+      }
+
+      const authorization = worldAuthorizationService.evaluateWorldAction({
+        worldId: world.worldId,
+        actorAgentId: senderAgentId,
+        action: WORLD_ACTIONS.BROADCAST,
+      });
+      const senderRole = authorization.worldRole;
+      if (!authorization.allowed) {
+        throw createBroadcastNotAllowedError({
+          worldId: world.worldId,
+          senderAgentId,
+          senderRole,
+        });
+      }
+
+      const effectiveAudience = normalizeBroadcastAudience(audience, worldBroadcast.audience || 'members');
+      const effectiveExcludeSelf = normalizeBoolean(excludeSelf, worldBroadcast.excludeSelf !== false) !== false;
+      const effectiveEligibility = normalizeWorldEligibility(world.eligibility, 'active');
+      const targetAgentIds = resolveAudienceAgentIds(world, {
+        audience: effectiveAudience,
+        excludeSelf: effectiveExcludeSelf,
+        senderAgentId,
+      });
+      const broadcastId = createBroadcastId();
+      const openingPayload = cloneJsonObject(payload) || { text: openingMessage };
+
+      const requests = [];
+      const failures = [];
+      for (const targetAgentId of targetAgentIds) {
+        const targetAgent = store.getAgent(targetAgentId);
+        if (!targetAgent?.address) {
+          failures.push({
+            agentId: targetAgentId,
+            status: 'failed',
+            httpStatus: 404,
+            error: 'target_not_found',
+            reason: 'target_not_found',
+            message: 'target agent is missing a relay address',
+          });
+          continue;
+        }
+
+        try {
+          const created = await chatRequestService.createChatRequest({
+            fromAgentId: senderAgentId,
+            targetAgentId,
+            openingMessage,
+            openingPayload,
+            worldId: world.worldId,
+            origin: {
+              type: 'world_broadcast',
+              broadcastId,
+            },
+            broadcast: {
+              broadcastId,
+              worldId: world.worldId,
+              audience: effectiveAudience,
+              senderRole,
+              eligibility: effectiveEligibility,
+              excludeSelf: effectiveExcludeSelf,
+            },
+            source: 'world_broadcast',
+          });
+
+          requests.push({
+            agentId: targetAgentId,
+            status: created.status,
+            verdict: created.verdict,
+            chatRequest: created.chatRequest,
+            kickoff: created.kickoff || null,
+          });
+        } catch (error) {
+          failures.push(normalizeBroadcastCreationError(error, {
+            agentId: targetAgentId,
+          }));
+        }
+      }
+
+      const pendingCount = requests.filter((item) => item.chatRequest?.status === 'pending').length;
+      const autoAcceptedCount = requests.filter((item) => item.chatRequest?.status === 'accepted').length;
+      const rejectedCount = requests.filter((item) => item.chatRequest?.status === 'rejected').length;
+
+      return {
+        status: failures.length === 0 ? 'requests_created' : 'requests_created_with_failures',
+        worldId: world.worldId,
+        senderAgentId,
+        senderRole,
+        audience: effectiveAudience,
+        excludeSelf: effectiveExcludeSelf,
+        eligibility: effectiveEligibility,
+        broadcastId,
+        totalTargets: targetAgentIds.length,
+        createdCount: requests.length,
+        failedCount: failures.length,
+        pendingCount,
+        autoAcceptedCount,
+        rejectedCount,
+        requests,
+        failures,
+        nextAction:
+          pendingCount > 0
+            ? 'recipients_review_pending_requests'
+            : autoAcceptedCount > 0
+              ? 'backend_auto_accepted_requests'
+              : rejectedCount > 0
+                ? 'requests_rejected_by_policy'
+                : 'no_pending_requests_created',
+      };
+    },
+  };
+}