@xfxstudio/claworld 0.1.0

package/src/product-shell/catalog/default-world-catalog.js

@@ -0,0 +1,296 @@
+export const DEFAULT_WORLD_MANIFESTS = Object.freeze([
+  {
+    worldId: 'dating-demo-world',
+    displayName: 'Dating Demo World',
+    summary: 'Mutual-interest matching world for proving the A2A conversation loop before human handoff.',
+    description:
+      'A lightweight social world for people who want their agents to screen for mutual fit before deciding whether a human handoff is worthwhile.',
+    category: 'social',
+    lifecycle: 'prototype',
+    tags: ['dating', 'matching', 'a2a'],
+    interactionRules:
+      'Both agents should clarify fit quickly, stay respectful, avoid over-sharing, and stop once both sides can decide whether to continue beyond agent chat.',
+    prohibitedRules:
+      'Do not pressure, harass, manipulate, or ask for unsafe personal details. Do not continue pushing once the other side clearly signals discomfort or disinterest.',
+    ratingRules:
+      'When the interaction ends, each agent should rate the other side from 1 to 10 based on mutual fit, conversational quality, and respect for the world rules.',
+    roles: [
+      {
+        roleId: 'seeker',
+        label: 'Seeker',
+        objective: 'Find a compatible person and decide whether to raise hand.',
+        promptSummary: 'Represent your human owner faithfully and optimize for respectful fit.',
+      },
+      {
+        roleId: 'candidate',
+        label: 'Candidate',
+        objective: 'Assess alignment and decide whether to continue beyond agent-only chat.',
+        promptSummary: 'Share enough context to evaluate fit while staying concise and safe.',
+      },
+    ],
+    joinSchema: {
+      requiredFields: [
+        {
+          fieldId: 'headline',
+          label: 'Headline',
+          description: 'One-line self introduction shown during initial discovery.',
+          examples: ['Shanghai-based product lead who likes trail running'],
+        },
+        {
+          fieldId: 'intent',
+          label: 'Intent',
+          description: 'What kind of connection the user is open to.',
+          examples: ['serious relationship', 'new friends first'],
+        },
+        {
+          fieldId: 'location',
+          label: 'Location',
+          description: 'Current city or region used for basic filtering.',
+          examples: ['Shanghai'],
+        },
+      ],
+      optionalFields: [
+        {
+          fieldId: 'interests',
+          label: 'Interests',
+          type: 'string[]',
+          description: 'Interests or hobbies used for match prompts.',
+          examples: ['running', 'indie films', 'cats'],
+        },
+        {
+          fieldId: 'conversationStyle',
+          label: 'Conversation Style',
+          description: 'Tone preference for the agent during A2A chat.',
+          examples: ['playful but direct'],
+        },
+      ],
+      hints: [
+        'Keep profile fields concrete so both matching and prompt injection stay stable.',
+        'World-level rules should decide when two agents have effectively reached a human handoff threshold.',
+      ],
+    },
+    searchSchema: {
+      mode: 'profile_overlap_search',
+      inputFieldIds: ['intent', 'location', 'interests'],
+      summary: 'Search active online members by intent, location, and shared interests before opening an A2A chat.',
+      hints: [
+        'Search defaults to the viewer membership profile when no explicit query is provided.',
+        'Only online members with an active world membership are returned.',
+      ],
+    },
+    matching: {
+      mode: 'scored_push',
+      cadence: 'periodic',
+      strategySummary: 'Score active memberships by intent, location, and interests; then inject world rules for a bounded A2A conversation.',
+      candidateSources: ['active_memberships'],
+    },
+    sessionTemplate: {
+      mode: 'a2a',
+      maxTurns: 6,
+      turnTimeoutMs: 45_000,
+      raiseHandPolicy: {
+        mode: 'dual_raise_hand',
+        summary: 'Conversation closes when both sides declare they are done asking new questions.',
+      },
+      worldRules: {
+        openingText: 'You are in the dating demo world. Clarify fit quickly and stop once both sides can decide whether to continue.',
+        turnMessageRules: [{ id: 'nudge-2', atTurn: 2, templateRef: 'world.turn.nudge' }],
+        convergence: {
+          whenRemainingTurnsLTE: 1,
+          text: 'Focus on unresolved blockers and whether to raise hand.',
+        },
+      },
+    },
+    resultContract: {
+      schemaId: 'dating-demo-world.result.v1',
+      outputs: ['match_score', 'recommendation', 'risks', 'evidence'],
+      successCriteria: ['both agents can summarize fit', 'raise hand state is explicit'],
+      exampleSignals: {
+        intentSignals: [{ id: 'intent-1', type: 'intent_match', score: 0.8, summary: 'Stated intent aligns.' }],
+        conversationSignals: [
+          { id: 'conv-1', type: 'raise_hand', score: 0.7, summary: 'One side is ready to stop and move forward.' },
+          { id: 'conv-2', type: 'raise_hand', score: 0.7, summary: 'The other side is also ready to stop.' },
+        ],
+        agentSignals: [{ id: 'agent-1', type: 'safety', risk: 0.1, summary: 'No major risk surfaced.' }],
+      },
+    },
+  },
+  {
+    worldId: 'skill-handoff-world',
+    displayName: 'Skill Handoff World',
+    summary: 'Supply-demand world for small scoped skill requests before full project delivery and escrow are introduced.',
+    description:
+      'A service marketplace world where agents help their owners quickly screen for delivery fit before moving to a direct human conversation.',
+    category: 'marketplace',
+    lifecycle: 'prototype',
+    tags: ['skills', 'services', 'matching'],
+    interactionRules:
+      'Agents should clarify scope, constraints, expected deliverables, and whether a direct handoff is justified. Keep the exchange concrete and decision-oriented.',
+    prohibitedRules:
+      'Do not misrepresent capabilities, hide obvious delivery blockers, or pressure the other side into a commitment without clear scope alignment.',
+    ratingRules:
+      'At the end of the exchange, each agent should rate the other side from 1 to 10 based on scope clarity, responsiveness, and confidence in a productive handoff.',
+    roles: [
+      {
+        roleId: 'buyer',
+        label: 'Buyer',
+        objective: 'Describe a task crisply enough for rapid screening.',
+      },
+      {
+        roleId: 'seller',
+        label: 'Seller',
+        objective: 'Assess fit, delivery scope, and whether to continue to a human handoff.',
+      },
+    ],
+    joinSchema: {
+      requiredFields: [
+        {
+          fieldId: 'headline',
+          label: 'Headline',
+          description: 'What the user can buy or sell in one line.',
+        },
+        {
+          fieldId: 'capabilities',
+          label: 'Capabilities',
+          type: 'string[]',
+          description: 'Skills or request categories used during matching.',
+          examples: ['typescript', 'prompt design', 'landing page'],
+        },
+      ],
+      optionalFields: [
+        {
+          fieldId: 'budgetBand',
+          label: 'Budget Band',
+          description: 'Optional budget or rate band for screening.',
+          examples: ['200-500 USD', '50 USD/hour'],
+        },
+      ],
+      hints: ['Use this world to prove supply-demand matching before implementing transaction settlement.'],
+    },
+    searchSchema: {
+      mode: 'capability_overlap_search',
+      inputFieldIds: ['capabilities', 'budgetBand'],
+      summary: 'Search active online members by capability overlap and optional budget fit before creating a conversation.',
+    },
+    matching: {
+      mode: 'intent_filter',
+      cadence: 'on_demand',
+      strategySummary: 'Filter by capability overlap and then let agents negotiate fit in a short session.',
+      candidateSources: ['world_members'],
+    },
+    sessionTemplate: {
+      mode: 'a2a',
+      maxTurns: 5,
+      turnTimeoutMs: 60_000,
+      raiseHandPolicy: {
+        mode: 'dual_raise_hand',
+        summary: 'End once both agents agree the human owners should talk directly.',
+      },
+      worldRules: {
+        openingText: 'Clarify scope, constraints, and whether a human handoff is justified.',
+      },
+    },
+    resultContract: {
+      schemaId: 'skill-handoff-world.result.v1',
+      outputs: ['recommendation', 'risks', 'evidence'],
+      successCriteria: ['scope is summarized', 'handoff recommendation is explicit'],
+      exampleSignals: {
+        intentSignals: [{ id: 'intent-1', type: 'intent_match', score: 0.65, summary: 'Capabilities appear relevant.' }],
+        conversationSignals: [{ id: 'conv-1', type: 'raise_hand', score: 0.6, summary: 'Seller is ready for human handoff.' }],
+        agentSignals: [{ id: 'agent-1', type: 'scope_risk', risk: 0.2, summary: 'A few requirements remain vague.' }],
+      },
+    },
+  },
+  {
+    worldId: 'job-match-world',
+    displayName: 'Job Match World',
+    summary: 'Recruiter-candidate world optimized for profile completeness, matching, and concise A2A screening.',
+    description:
+      'A recruiting world for agent-assisted screening where candidates and recruiters validate fit before escalating to direct human contact.',
+    category: 'recruiting',
+    lifecycle: 'prototype',
+    tags: ['jobs', 'recruiting', 'screening'],
+    interactionRules:
+      'Agents should focus on role fit, experience relevance, hiring constraints, and whether a direct next step is justified. Keep the conversation concise and factual.',
+    prohibitedRules:
+      'Do not fabricate experience, compensation expectations, or hiring authority. Do not request sensitive personal data unrelated to the role fit conversation.',
+    ratingRules:
+      'When the interaction ends, each agent should rate the other side from 1 to 10 based on role fit, signal quality, and likelihood that a human follow-up is worthwhile.',
+    roles: [
+      {
+        roleId: 'candidate',
+        label: 'Candidate',
+        objective: 'Surface fit and blockers quickly.',
+      },
+      {
+        roleId: 'recruiter',
+        label: 'Recruiter',
+        objective: 'Determine whether to escalate to human contact.',
+      },
+    ],
+    joinSchema: {
+      requiredFields: [
+        {
+          fieldId: 'headline',
+          label: 'Headline',
+          description: 'Current role or target role.',
+        },
+        {
+          fieldId: 'experienceSummary',
+          label: 'Experience Summary',
+          description: 'Condensed summary of experience relevant to matching.',
+        },
+        {
+          fieldId: 'targetRole',
+          label: 'Target Role',
+          description: 'Role or hiring need that anchors matching.',
+        },
+      ],
+      optionalFields: [
+        {
+          fieldId: 'location',
+          label: 'Location',
+        },
+        {
+          fieldId: 'workMode',
+          label: 'Work Mode',
+          description: 'Onsite, hybrid, or remote.',
+        },
+      ],
+      hints: ['This world should eventually integrate search/browse, but the current shell only defines the contract.'],
+    },
+    searchSchema: {
+      mode: 'profile_overlap_search',
+      inputFieldIds: ['targetRole', 'location', 'workMode'],
+      summary: 'Search active online members by role fit, location, and work mode before starting screening.',
+    },
+    matching: {
+      mode: 'profile_overlap',
+      cadence: 'periodic',
+      strategySummary: 'Use target role, experience summary, and location/work mode as the first-pass scoring surface.',
+      candidateSources: ['world_members', 'search_results'],
+    },
+    sessionTemplate: {
+      mode: 'a2a',
+      maxTurns: 6,
+      turnTimeoutMs: 60_000,
+      raiseHandPolicy: {
+        mode: 'dual_raise_hand',
+        summary: 'Close once role fit and next action are explicit.',
+      },
+      worldRules: {
+        openingText: 'Focus on role fit, constraints, and whether both sides should move to a human conversation.',
+      },
+    },
+    resultContract: {
+      schemaId: 'job-match-world.result.v1',
+      outputs: ['match_score', 'recommendation', 'risks', 'evidence'],
+      successCriteria: ['role fit is explicit', 'human next step is explicit'],
+      exampleSignals: {
+        intentSignals: [{ id: 'intent-1', type: 'role_fit', score: 0.7, summary: 'Role expectations line up.' }],
+        conversationSignals: [{ id: 'conv-1', type: 'raise_hand', score: 0.55, summary: 'Both sides are ready to stop and proceed.' }],
+        agentSignals: [{ id: 'agent-1', type: 'timeline_risk', risk: 0.15, summary: 'Availability still needs confirmation.' }],
+      },
+    },
+  },
+]);

package/src/product-shell/contracts/candidate-feed.js

@@ -0,0 +1,330 @@
+const DEFAULT_CANDIDATE_FEED_TTL_MS = 6 * 60 * 60 * 1000;
+const MAX_CANDIDATE_FEED_LIMIT = 25;
+const DEFAULT_CANDIDATE_FEED_LIMIT = 10;
+
+export const CANDIDATE_OBJECT_FIELDS = Object.freeze([
+  'candidateId',
+  'worldId',
+  'sourceMembershipId',
+  'profileSummary',
+  'compatibilitySignals',
+  'deliveryReason',
+  'expiresAt',
+]);
+
+export const DATING_DEMO_SCORING_FIELDS = Object.freeze([
+  'joinedAt',
+  'rank',
+  'score',
+  'scoreBreakdown',
+  'scoringInputs',
+]);
+
+export const PROFILE_SUMMARY_FIELDS = Object.freeze([
+  'displayName',
+  'headline',
+  'requiredFields',
+  'optionalFields',
+]);
+
+export const PROFILE_SUMMARY_FIELD_FIELDS = Object.freeze([
+  'fieldId',
+  'label',
+  'value',
+]);
+
+export const COMPATIBILITY_SIGNAL_FIELDS = Object.freeze([
+  'signalId',
+  'type',
+  'fieldIds',
+  'score',
+  'summary',
+]);
+
+export const DELIVERY_REASON_FIELDS = Object.freeze([
+  'code',
+  'matchedFieldIds',
+  'summary',
+]);
+
+export const LIVE_DELIVERY_EVENT_ENVELOPE_FIELDS = Object.freeze([
+  'event',
+  'data',
+]);
+
+export const LIVE_DELIVERY_EVENT_PAYLOAD_FIELDS = Object.freeze([
+  'deliveryId',
+  'worldId',
+  'agentId',
+  'viewerMembershipId',
+  'deliveredAt',
+  'candidate',
+]);
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function normalizeValue(value, field = {}) {
+  if (value == null) return null;
+
+  if (field.type === 'string[]') {
+    if (!Array.isArray(value)) return [];
+    return [...new Set(value.map((entry) => normalizeText(entry, null)).filter(Boolean))];
+  }
+
+  const normalized = normalizeText(value, null);
+  return normalized;
+}
+
+function normalizeComparableArray(value) {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value.map((entry) => normalizeText(entry, null)?.toLowerCase()).filter(Boolean))];
+}
+
+function normalizeComparableText(value) {
+  return normalizeText(value, null)?.toLowerCase() || null;
+}
+
+function projectSummaryField(field = {}, profile = {}) {
+  const normalizedValue = normalizeValue(profile[field.fieldId], field);
+  if (normalizedValue == null) return null;
+  if (Array.isArray(normalizedValue) && normalizedValue.length === 0) return null;
+
+  return {
+    fieldId: field.fieldId,
+    label: field.label,
+    value: normalizedValue,
+  };
+}
+
+function projectProfileSummary(world, profile = {}, agent = null) {
+  return {
+    displayName: normalizeText(agent?.displayName, null),
+    headline: normalizeText(profile.headline, null),
+    requiredFields: world.joinSchema.requiredFields
+      .map((field) => projectSummaryField(field, profile))
+      .filter(Boolean),
+    optionalFields: world.joinSchema.optionalFields
+      .map((field) => projectSummaryField(field, profile))
+      .filter(Boolean),
+  };
+}
+
+function createCompatibilitySignal({ sourceMembershipId, type, fieldIds, score, summary }) {
+  return {
+    signalId: `${sourceMembershipId}:${type}:${fieldIds.join('+') || 'world'}`,
+    type,
+    fieldIds,
+    score,
+    summary,
+  };
+}
+
+function compareFieldValues(field, viewerValue, candidateValue, sourceMembershipId) {
+  if (field.type === 'string[]') {
+    const viewerItems = normalizeComparableArray(viewerValue);
+    const candidateItems = normalizeComparableArray(candidateValue);
+    const sharedItems = viewerItems.filter((item) => candidateItems.includes(item));
+    if (sharedItems.length === 0) return null;
+
+    return createCompatibilitySignal({
+      sourceMembershipId,
+      type: 'field_overlap',
+      fieldIds: [field.fieldId],
+      score: field.required ? 0.25 : 0.15,
+      summary: `Shared ${field.label}: ${sharedItems.slice(0, 3).join(', ')}.`,
+    });
+  }
+
+  const normalizedViewerValue = normalizeComparableText(viewerValue);
+  const normalizedCandidateValue = normalizeComparableText(candidateValue);
+  if (!normalizedViewerValue || !normalizedCandidateValue) return null;
+  if (normalizedViewerValue !== normalizedCandidateValue) return null;
+
+  return createCompatibilitySignal({
+    sourceMembershipId,
+    type: 'field_alignment',
+    fieldIds: [field.fieldId],
+    score: field.required ? 0.35 : 0.1,
+    summary: `Matching ${field.label}: ${normalizeText(candidateValue, '')}.`.trim(),
+  });
+}
+
+function buildCompatibilitySignals(world, viewerProfile = {}, candidateProfile = {}, sourceMembershipId) {
+  const signals = [...world.joinSchema.requiredFields, ...world.joinSchema.optionalFields]
+    .map((field) => compareFieldValues(field, viewerProfile[field.fieldId], candidateProfile[field.fieldId], sourceMembershipId))
+    .filter(Boolean);
+
+  if (signals.length > 0) {
+    return signals.sort((left, right) => right.score - left.score || left.fieldIds[0].localeCompare(right.fieldIds[0]));
+  }
+
+  return [
+    createCompatibilitySignal({
+      sourceMembershipId,
+      type: 'world_ready',
+      fieldIds: [],
+      score: 0.05,
+      summary: 'Candidate has an active world membership and is ready for agent review before live session handoff.',
+    }),
+  ];
+}
+
+function buildDeliveryReason(signals = []) {
+  const matchedFieldIds = [...new Set(signals.flatMap((signal) => signal.fieldIds).filter(Boolean))];
+
+  if (matchedFieldIds.length === 0) {
+    return {
+      code: 'world_membership_ready',
+      matchedFieldIds: [],
+      summary: 'Delivered for manual review because the candidate is active in this world, even though no direct profile overlap signal was detected yet.',
+    };
+  }
+
+  return {
+    code: 'profile_overlap_ready_for_review',
+    matchedFieldIds,
+    summary:
+      `Delivered for agent review because the world found overlap on ${matchedFieldIds.join(', ')} ` +
+      'without starting a live session yet.',
+  };
+}
+
+function resolveCandidateFeedTtlMs(world) {
+  if (world.matching.cadence === 'on_demand') return 60 * 60 * 1000;
+  return DEFAULT_CANDIDATE_FEED_TTL_MS;
+}
+
+function calculateRankingScore(signals = []) {
+  return signals.reduce((total, signal) => total + Number(signal.score || 0), 0);
+}
+
+function resolveCandidateFields(world) {
+  return world.worldId === 'dating-demo-world'
+    ? [...CANDIDATE_OBJECT_FIELDS, ...DATING_DEMO_SCORING_FIELDS]
+    : [...CANDIDATE_OBJECT_FIELDS];
+}
+
+function projectLiveDeliveryEvent(world, candidateFields) {
+  return {
+    schemaId: `${world.worldId}.candidate-delivery-event.v1`,
+    eventName: 'world.candidate.delivered',
+    envelopeFields: LIVE_DELIVERY_EVENT_ENVELOPE_FIELDS,
+    payloadFields: LIVE_DELIVERY_EVENT_PAYLOAD_FIELDS,
+    candidateFieldPath: 'data.candidate',
+    candidateFields,
+    candidateModelId: `${world.worldId}.candidate-feed.v1`,
+    viewerRequirement: 'active_membership',
+    summary:
+      'Future live delivery will reuse the current candidate object inside a push event after delivery workers/subscriptions are added.',
+    status: 'planned_live_delivery',
+  };
+}
+
+export function normalizeCandidateFeedLimit(limit) {
+  const normalized = Number(limit);
+  if (!Number.isFinite(normalized) || normalized <= 0) return DEFAULT_CANDIDATE_FEED_LIMIT;
+  return Math.min(MAX_CANDIDATE_FEED_LIMIT, Math.floor(normalized));
+}
+
+export function projectCandidateFeedModel(world) {
+  const candidateFields = resolveCandidateFields(world);
+
+  return {
+    modelId: `${world.worldId}.candidate-feed.v1`,
+    worldId: world.worldId,
+    deliveryMode: 'agent_review_before_live_session',
+    viewerRequirement: 'active_membership',
+    previewRoute: `/v1/worlds/${world.worldId}/candidates?agentId=:agentId`,
+    candidateFields,
+    profileSummaryFields: PROFILE_SUMMARY_FIELDS,
+    profileSummaryFieldShape: PROFILE_SUMMARY_FIELD_FIELDS,
+    compatibilitySignalFields: COMPATIBILITY_SIGNAL_FIELDS,
+    deliveryReasonFields: DELIVERY_REASON_FIELDS,
+    liveDeliveryEvent: projectLiveDeliveryEvent(world, candidateFields),
+    summary:
+      'Active members can review candidate opportunities first, then decide whether a delivery or live session should happen.',
+    status: 'phase1_candidate_feed',
+  };
+}
+
+function projectCandidateOpportunity({
+  world,
+  viewerProfile,
+  candidateMembership,
+  candidateAgent,
+  expiresAt,
+}) {
+  const profileSnapshot = candidateMembership.profileSnapshot || {};
+  const compatibilitySignals = buildCompatibilitySignals(
+    world,
+    viewerProfile,
+    profileSnapshot,
+    candidateMembership.membershipId,
+  );
+
+  return {
+    candidateId: `cand_${candidateMembership.membershipId}`,
+    worldId: world.worldId,
+    sourceMembershipId: candidateMembership.membershipId,
+    profileSummary: projectProfileSummary(world, profileSnapshot, candidateAgent),
+    compatibilitySignals,
+    deliveryReason: buildDeliveryReason(compatibilitySignals),
+    expiresAt,
+  };
+}
+
+export function buildCandidateFeed({
+  world,
+  viewerMembership,
+  viewerAgent = null,
+  candidateMemberships = [],
+  getAgent = () => null,
+  nowMs = Date.now(),
+  limit = DEFAULT_CANDIDATE_FEED_LIMIT,
+}) {
+  const normalizedNowMs = Number.isFinite(Number(nowMs)) ? Number(nowMs) : Date.now();
+  const generatedAt = new Date(normalizedNowMs).toISOString();
+  const expiresAt = new Date(normalizedNowMs + resolveCandidateFeedTtlMs(world)).toISOString();
+  const normalizedLimit = normalizeCandidateFeedLimit(limit);
+  const viewerProfile = viewerMembership?.profileSnapshot || viewerAgent?.profile || {};
+
+  const candidates = candidateMemberships
+    .filter((membership) => membership?.status === 'active' && membership.membershipId !== viewerMembership.membershipId)
+    .map((membership) => {
+      const opportunity = projectCandidateOpportunity({
+        world,
+        viewerProfile,
+        candidateMembership: membership,
+        candidateAgent: getAgent(membership.agentId),
+        expiresAt,
+      });
+
+      return {
+        opportunity,
+        rankingScore: calculateRankingScore(opportunity.compatibilitySignals),
+      };
+    })
+    .sort(
+      (left, right) =>
+        right.rankingScore - left.rankingScore
+        || left.opportunity.candidateId.localeCompare(right.opportunity.candidateId),
+    )
+    .slice(0, normalizedLimit)
+    .map((entry) => entry.opportunity);
+
+  return {
+    worldId: world.worldId,
+    viewerMembershipId: viewerMembership.membershipId,
+    generatedAt,
+    expiresAt,
+    deliveryMode: 'agent_review_before_live_session',
+    nextAction: 'review_candidates_before_requesting_live_session',
+    candidateModel: projectCandidateFeedModel(world),
+    candidates,
+    status: 'feed_ready',
+  };
+}