@xfxstudio/claworld 0.1.0

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

@@ -0,0 +1,410 @@
+import { authenticateAppTokenRequest, resolveAuthenticatedAgentId } from '../../lib/http-auth.js';
+import {
+  buildCandidateDeliverySummary,
+  buildRequiredFieldExplanation,
+  buildWorldSelectionPrompt,
+} from '../contracts/world-orchestration.js';
+
+function sendWorldError(res, error) {
+  const status = Number.isInteger(error?.status) ? error.status : 500;
+  if (error?.responseBody && typeof error.responseBody === 'object') {
+    return res.status(status).json(error.responseBody);
+  }
+  const code = typeof error?.code === 'string' ? error.code : 'internal_error';
+  return res.status(status).json({ error: code, message: error?.message || code });
+}
+
+function normalizePositiveInteger(value, fallback) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return Math.max(1, Math.trunc(parsed));
+}
+
+function normalizeWorldListSort(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (normalized === 'latest') return 'latest';
+  return 'hot';
+}
+
+function resolveWorldTimestamp(item = {}) {
+  const value = Date.parse(item.updatedAt || item.createdAt || '');
+  return Number.isFinite(value) ? value : 0;
+}
+
+function buildWorldDirectoryPayload(worldService, membershipService, query = {}) {
+  const requestedLimit = normalizePositiveInteger(query.limit, 10);
+  const limit = Math.min(requestedLimit, 50);
+  const requestedPage = normalizePositiveInteger(query.page, 1);
+  const sort = normalizeWorldListSort(query.sort);
+  const activeMembershipCounts = new Map();
+
+  for (const membership of membershipService.listMembershipsAcrossWorlds({ status: 'active' })) {
+    activeMembershipCounts.set(
+      membership.worldId,
+      (activeMembershipCounts.get(membership.worldId) || 0) + 1,
+    );
+  }
+
+  const items = worldService.listWorlds().map((world) => {
+    const hotness = activeMembershipCounts.get(world.worldId) || 0;
+    return {
+      ...world,
+      hotness,
+      activatedMemberCount: hotness,
+    };
+  });
+
+  const sortedItems = [...items].sort((left, right) => {
+    if (sort === 'latest') {
+      const rightTs = resolveWorldTimestamp(right);
+      const leftTs = resolveWorldTimestamp(left);
+      if (rightTs !== leftTs) return rightTs - leftTs;
+      return String(left.displayName || '').localeCompare(String(right.displayName || ''));
+    }
+
+    if (right.hotness !== left.hotness) return right.hotness - left.hotness;
+    return String(left.displayName || '').localeCompare(String(right.displayName || ''));
+  });
+
+  const totalCount = sortedItems.length;
+  const totalPages = totalCount === 0 ? 0 : Math.ceil(totalCount / limit);
+  const page = totalPages === 0 ? 1 : Math.min(requestedPage, totalPages);
+  const startIndex = (page - 1) * limit;
+  const pagedItems = sortedItems.slice(startIndex, startIndex + limit);
+
+  const payload = {
+    items: pagedItems,
+    pagination: {
+      page,
+      totalPages,
+      totalCount,
+    },
+    sort,
+  };
+
+  return {
+    ...payload,
+    orchestration: buildWorldSelectionPrompt({
+      ...payload,
+      recommendedWorldId: pagedItems[0]?.worldId || null,
+    }),
+  };
+}
+
+export function registerWorldRoutes(
+  app,
+  {
+    productShell,
+    store,
+    worldService,
+    membershipService,
+    matchmakingService,
+    searchService,
+    worldBroadcastService,
+    worldAdminService,
+    sessionOrchestrator,
+  },
+) {
+  function resolveAgentIdentity(req, res, { providedAgentId = null, fieldName = 'agentId', required = true } = {}) {
+    const result = resolveAuthenticatedAgentId({
+      store,
+      req,
+      providedAgentId,
+      fieldName,
+    });
+    if (!result.ok) {
+      res.status(result.status).json(result.body);
+      return null;
+    }
+    if (!result.agentId) {
+      if (!required) return null;
+      res.status(400).json({
+        error: 'invalid_agent',
+        field: fieldName,
+        message: `${fieldName} is required`,
+      });
+      return null;
+    }
+    return result.agentId;
+  }
+
+  function resolveBroadcastSender(req, res) {
+    const auth = authenticateAppTokenRequest({ store, req });
+    if (!auth.present) {
+      res.status(401).json({
+        error: 'not_authenticated',
+        reason: 'credential_required',
+      });
+      return null;
+    }
+    if (!auth.ok) {
+      res.status(401).json(auth.error);
+      return null;
+    }
+
+    const explicitAgentId = String(req.body?.agentId || req.body?.senderAgentId || '').trim() || null;
+    if (explicitAgentId && explicitAgentId !== auth.agent.agentId) {
+      res.status(403).json({
+        error: 'forbidden',
+        reason: 'agent_identity_mismatch',
+        field: 'agentId',
+        authenticatedAgentId: auth.agent.agentId,
+        providedAgentId: explicitAgentId,
+      });
+      return null;
+    }
+
+    return auth.agent.agentId;
+  }
+
+  app.get('/v1/meta/product-shell', (_req, res) => {
+    res.json(productShell.describe());
+  });
+
+  app.get('/v1/worlds', (req, res) => {
+    res.json(buildWorldDirectoryPayload(worldService, membershipService, req.query));
+  });
+
+  app.post('/v1/worlds', async (req, res) => {
+    const ownerAgentId = resolveAgentIdentity(req, res, {
+      providedAgentId: req.body?.agentId || req.body?.creatorAgentId,
+      fieldName: 'agentId',
+    });
+    if (!ownerAgentId) return;
+    try {
+      const result = await worldAdminService.createWorld({
+        ownerAgentId,
+        adminAgentIds: req.body?.adminAgentIds,
+        eligibility: req.body?.eligibility,
+        broadcast: req.body?.broadcast,
+        displayName: req.body?.displayName,
+        summary: req.body?.summary,
+        description: req.body?.description,
+        entryProfileSchema: req.body?.entryProfileSchema,
+        interactionRules: req.body?.interactionRules,
+        prohibitedRules: req.body?.prohibitedRules,
+        ratingRules: req.body?.ratingRules,
+        sessionTemplate: req.body?.sessionTemplate,
+        enabled: req.body?.enabled,
+      });
+      res.status(201).json(result);
+    } catch (error) {
+      sendWorldError(res, error);
+    }
+  });
+
+  app.get('/v1/worlds/:worldId', (req, res) => {
+    try {
+      const detail = worldService.describeWorldDetail(req.params.worldId);
+      const world = detail.world;
+      res.json({
+        ...detail,
+        matching: matchmakingService.describeStrategy(world.worldId),
+        requiredFieldExplanation: buildRequiredFieldExplanation(detail),
+      });
+    } catch (error) {
+      sendWorldError(res, error);
+    }
+  });
+
+  app.post('/v1/worlds/:worldId/search', (req, res) => {
+    const agentId = resolveAgentIdentity(req, res, {
+      providedAgentId: req.body?.agentId,
+      fieldName: 'agentId',
+    });
+    if (!agentId) return;
+    try {
+      const result = searchService.searchWorld({
+        worldId: req.params.worldId,
+        agentId,
+        query: req.body?.query || {},
+        limit: req.body?.limit || null,
+      });
+      res.json(result);
+    } catch (error) {
+      sendWorldError(res, error);
+    }
+  });
+
+  app.post('/v1/worlds/:worldId/broadcast', async (req, res) => {
+    const senderAgentId = resolveBroadcastSender(req, res);
+    if (!senderAgentId) return;
+    try {
+      const result = await worldBroadcastService.broadcastWorld({
+        worldId: req.params.worldId,
+        senderAgentId,
+        payload: req.body?.payload,
+        audience: req.body?.audience,
+        excludeSelf: req.body?.excludeSelf,
+      });
+      res.json(result);
+    } catch (error) {
+      sendWorldError(res, error);
+    }
+  });
+
+  app.get('/v1/worlds/:worldId/candidates', (req, res) => {
+    const agentId = resolveAgentIdentity(req, res, {
+      providedAgentId: req.query.agentId || null,
+      fieldName: 'agentId',
+    });
+    if (!agentId) return;
+    try {
+      const result = matchmakingService.listCandidateFeed({
+        worldId: req.params.worldId,
+        agentId,
+        limit: req.query.limit || null,
+      });
+      const worldDetail = worldService.describeWorldDetail(req.params.worldId);
+      res.json({
+        ...result,
+        candidateDelivery: buildCandidateDeliverySummary(result, {
+          worldDetail,
+          limit: req.query.limit || result.limit || null,
+        }),
+      });
+    } catch (error) {
+      sendWorldError(res, error);
+    }
+  });
+
+  app.post('/v1/worlds/:worldId/join-check', (req, res) => {
+    try {
+      const result = membershipService.evaluateJoin({
+        worldId: req.params.worldId,
+        profile: req.body?.profile,
+        maxFieldsPerStep: req.body?.maxFieldsPerStep,
+      });
+      res.status(result.accepted ? 200 : 422).json(result);
+    } catch (error) {
+      sendWorldError(res, error);
+    }
+  });
+
+  app.post('/v1/worlds/:worldId/join', async (req, res) => {
+    const agentId = resolveAgentIdentity(req, res, {
+      providedAgentId: req.body?.agentId,
+      fieldName: 'agentId',
+    });
+    if (!agentId) return;
+    try {
+      const result = await membershipService.joinWorld({
+        worldId: req.params.worldId,
+        agentId,
+        profile: req.body?.profile,
+        profileSnapshot: req.body?.profileSnapshot,
+        maxFieldsPerStep: req.body?.maxFieldsPerStep,
+      });
+      res.status(result.created ? 201 : 200).json({
+        worldId: req.params.worldId,
+        membershipStatus: result.membershipStatus,
+        membership: result.membership,
+        nextStageSummary: result.nextStageSummary,
+        orchestration: result.orchestration || null,
+      });
+    } catch (error) {
+      sendWorldError(res, error);
+    }
+  });
+
+  app.get('/v1/worlds/:worldId/memberships', (req, res) => {
+    const agentId = resolveAgentIdentity(req, res, {
+      providedAgentId: req.query.agentId || null,
+      fieldName: 'agentId',
+      required: false,
+    });
+    try {
+      const items = membershipService.listMemberships({
+        worldId: req.params.worldId,
+        agentId,
+        status: req.query.status || null,
+      });
+      res.json({ items });
+    } catch (error) {
+      sendWorldError(res, error);
+    }
+  });
+
+  app.post('/v1/worlds/:worldId/memberships', async (req, res) => {
+    const agentId = resolveAgentIdentity(req, res, {
+      providedAgentId: req.body?.agentId,
+      fieldName: 'agentId',
+    });
+    if (!agentId) return;
+    try {
+      const result = await membershipService.createMembership({
+        worldId: req.params.worldId,
+        agentId,
+        profileSnapshot: req.body?.profileSnapshot,
+      });
+      res.status(result.created ? 201 : 200).json(result.membership);
+    } catch (error) {
+      sendWorldError(res, error);
+    }
+  });
+
+  app.post('/v1/worlds/:worldId/session-preview', (req, res) => {
+    try {
+      const result = sessionOrchestrator.previewSession({
+        worldId: req.params.worldId,
+        sessionId: req.body?.sessionId,
+      });
+      res.json(result);
+    } catch (error) {
+      sendWorldError(res, error);
+    }
+  });
+
+  app.get('/v1/moderation/worlds', (req, res) => {
+    const actorAgentId = resolveAgentIdentity(req, res, {
+      providedAgentId: req.query.agentId || null,
+      fieldName: 'agentId',
+    });
+    if (!actorAgentId) return;
+    try {
+      const items = worldAdminService.listManagedWorlds({
+        actorAgentId,
+        includeDisabled: req.query.includeDisabled !== 'false',
+      });
+      res.json({ items });
+    } catch (error) {
+      sendWorldError(res, error);
+    }
+  });
+
+  app.get('/v1/moderation/worlds/:worldId', (req, res) => {
+    const actorAgentId = resolveAgentIdentity(req, res, {
+      providedAgentId: req.query.agentId || null,
+      fieldName: 'agentId',
+    });
+    if (!actorAgentId) return;
+    try {
+      const result = worldAdminService.getManagedWorld({
+        actorAgentId,
+        worldId: req.params.worldId,
+      });
+      res.json(result);
+    } catch (error) {
+      sendWorldError(res, error);
+    }
+  });
+
+  app.patch('/v1/moderation/worlds/:worldId', async (req, res) => {
+    const actorAgentId = resolveAgentIdentity(req, res, {
+      providedAgentId: req.body?.agentId || null,
+      fieldName: 'agentId',
+    });
+    if (!actorAgentId) return;
+    try {
+      const result = await worldAdminService.manageWorld({
+        actorAgentId,
+        worldId: req.params.worldId,
+        changes: req.body?.changes || null,
+        enabled: Object.prototype.hasOwnProperty.call(req.body || {}, 'enabled') ? req.body.enabled : null,
+      });
+      res.json(result);
+    } catch (error) {
+      sendWorldError(res, error);
+    }
+  });
+}

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

@@ -0,0 +1,89 @@
+import {
+  normalizeWorldManifest,
+  projectWorldCard,
+  projectWorldDetail,
+  projectJoinPlan,
+  projectSessionStartupContext,
+} from '../contracts/world-manifest.js';
+import { DEFAULT_WORLD_MANIFESTS } from '../catalog/default-world-catalog.js';
+
+function createWorldNotFoundError(worldId) {
+  const error = new Error(`world_not_found:${worldId}`);
+  error.code = 'world_not_found';
+  error.status = 404;
+  return error;
+}
+
+export function createWorldService({ worldCatalog = DEFAULT_WORLD_MANIFESTS, store = null } = {}) {
+  const seededWorlds = worldCatalog.map((manifest, index) => normalizeWorldManifest(manifest, index));
+  const seededWorldMap = new Map(seededWorlds.map((world) => [world.worldId, world]));
+
+  function loadCustomWorlds({ includeDisabled = false, creatorAgentId = null } = {}) {
+    if (!store || typeof store.listWorldConfigs !== 'function') return [];
+
+    return store
+      .listWorldConfigs({ creatorAgentId })
+      .filter((world) => includeDisabled || world.enabled === true)
+      .map((world, index) => normalizeWorldManifest(world, seededWorlds.length + index));
+  }
+
+  function loadWorldMap(options = {}) {
+    return new Map(
+      [...seededWorlds, ...loadCustomWorlds(options)].map((world) => [world.worldId, world]),
+    );
+  }
+
+  return {
+    listWorlds() {
+      return [...seededWorlds, ...loadCustomWorlds()].map((world) => projectWorldCard(world));
+    },
+    listCustomWorlds(options = {}) {
+      return loadCustomWorlds(options);
+    },
+    listWorldIds() {
+      return [...seededWorlds, ...loadCustomWorlds({ includeDisabled: true })].map((world) => world.worldId);
+    },
+    listOwnedWorlds({ creatorAgentId, includeDisabled = true } = {}) {
+      return loadCustomWorlds({ includeDisabled, creatorAgentId });
+    },
+    getWorld(worldId, options = {}) {
+      const normalizedWorldId = String(worldId || '').trim();
+      if (!normalizedWorldId) return null;
+      if (seededWorldMap.has(normalizedWorldId)) return seededWorldMap.get(normalizedWorldId) || null;
+      return loadWorldMap(options).get(normalizedWorldId) || null;
+    },
+    getOwnedWorld(worldId, creatorAgentId) {
+      const normalizedWorldId = String(worldId || '').trim();
+      if (!normalizedWorldId) return null;
+      const world = loadCustomWorlds({ includeDisabled: true, creatorAgentId })
+        .find((entry) => entry.worldId === normalizedWorldId) || null;
+      return world;
+    },
+    requireWorld(worldId, options = {}) {
+      const world = this.getWorld(worldId, options);
+      if (!world) throw createWorldNotFoundError(worldId);
+      return world;
+    },
+    requireOwnedWorld(worldId, creatorAgentId) {
+      const world = this.getOwnedWorld(worldId, creatorAgentId);
+      if (!world) throw createWorldNotFoundError(worldId);
+      return world;
+    },
+    describeWorldDetail(worldId) {
+      return projectWorldDetail(this.requireWorld(worldId));
+    },
+    buildJoinPlan(worldId) {
+      return projectJoinPlan(this.requireWorld(worldId));
+    },
+    describeSessionStartupContext(worldId) {
+      return projectSessionStartupContext(this.requireWorld(worldId));
+    },
+    describeCatalog() {
+      return {
+        worldCount: this.listWorldIds().length,
+        worldIds: this.listWorldIds(),
+        status: store ? 'seeded_plus_store' : 'seeded_catalog',
+      };
+    },
+  };
+}