@xfxstudio/claworld 0.1.4 → 0.2.0

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

@@ -0,0 +1,77 @@
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function normalizeStringList(values = []) {
+  if (!Array.isArray(values)) return [];
+  return [...new Set(values.map((value) => normalizeText(value, null)).filter(Boolean))];
+}
+
+function formatProfileValue(value) {
+  if (value == null) return null;
+  if (typeof value === 'string') return normalizeText(value, null);
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  if (Array.isArray(value)) {
+    const normalized = normalizeStringList(value);
+    return normalized.length > 0 ? normalized.join(', ') : null;
+  }
+  return null;
+}
+
+export function buildWorldContextText({
+  worldId = null,
+  displayName = null,
+  summary = null,
+  worldContextText = null,
+  interactionRules = null,
+  prohibitedRules = null,
+  ratingRules = null,
+} = {}) {
+  const explicitWorldContextText = normalizeText(worldContextText, null);
+  if (explicitWorldContextText) return explicitWorldContextText;
+
+  const normalizedWorldId = normalizeText(worldId, null);
+  const normalizedDisplayName = normalizeText(displayName, normalizedWorldId);
+  const lines = [
+    normalizedDisplayName
+      ? `世界：${normalizedDisplayName}${normalizedWorldId ? ` [${normalizedWorldId}]` : ''}`
+      : (normalizedWorldId ? `世界：${normalizedWorldId}` : null),
+    normalizeText(summary, null) ? `简介：${normalizeText(summary, null)}` : null,
+    normalizeText(interactionRules, null) ? `互动规则：${normalizeText(interactionRules, null)}` : null,
+    normalizeText(prohibitedRules, null) ? `禁止事项：${normalizeText(prohibitedRules, null)}` : null,
+    normalizeText(ratingRules, null) ? `结果要求：${normalizeText(ratingRules, null)}` : null,
+  ].filter(Boolean);
+
+  return lines.length > 0 ? lines.join('\n') : null;
+}
+
+export function buildParticipantContextText({
+  world = null,
+  agent = null,
+  participantContextText = null,
+  profileSnapshot = null,
+} = {}) {
+  const explicitParticipantContextText = normalizeText(participantContextText, null);
+  if (explicitParticipantContextText) return explicitParticipantContextText;
+
+  const normalizedProfileSnapshot = profileSnapshot && typeof profileSnapshot === 'object' && !Array.isArray(profileSnapshot)
+    ? profileSnapshot
+    : {};
+  const normalizedProfileText = normalizeText(normalizedProfileSnapshot.participantContextText, null);
+  if (normalizedProfileText) return normalizedProfileText;
+
+  const lines = [
+    normalizeText(agent?.displayName, null) ? `名称：${normalizeText(agent.displayName, null)}` : null,
+    normalizeText(normalizedProfileSnapshot.headline, null) ? `简介：${normalizeText(normalizedProfileSnapshot.headline, null)}` : null,
+    ...Object.entries(normalizedProfileSnapshot).map(([fieldId, rawValue]) => {
+      if (fieldId === 'headline' || fieldId === 'participantContextText') return null;
+      const value = formatProfileValue(rawValue);
+      if (!value) return null;
+      return `${fieldId}：${value}`;
+    }),
+  ].filter(Boolean);
+
+  return lines.length > 0 ? lines.join('\n') : null;
+}

package/src/lib/runtime-guidance.js

@@ -1,457 +0,0 @@
-const DEFAULT_TEMPLATE_REFS = {
-  opening: 'world.session.opening',
-  convergence: 'world.session.convergence',
-  stateChanged: 'world.session.state_changed',
-};
-
-const CLAWORLD_RAISE_HAND_DIRECTIVE = '[[CLAWORLD_RAISE_HAND]]';
-
-function normalizeText(value, fallback = null) {
-  if (value == null) return fallback;
-  const normalized = String(value).trim();
-  return normalized || fallback;
-}
-
-function normalizeInteger(value, fallback = null) {
-  const normalized = Number(value);
-  if (!Number.isFinite(normalized)) return fallback;
-  return Math.trunc(normalized);
-}
-
-function normalizePositiveInteger(value, fallback = null) {
-  const normalized = normalizeInteger(value, fallback);
-  if (normalized == null || normalized <= 0) return fallback;
-  return normalized;
-}
-
-function normalizeTurnRule(rule = {}, index = 0) {
-  return {
-    id: rule.id || `turn_rule_${index + 1}`,
-    trigger: rule.trigger || 'turn_threshold',
-    atTurn: Number.isFinite(Number(rule.atTurn)) ? Math.max(0, Number(rule.atTurn)) : null,
-    visibility: rule.visibility || 'both',
-    role: rule.role || 'system',
-    templateRef: rule.templateRef || `world.turn.rule.${index + 1}`,
-    text: rule.text || null,
-    once: rule.once !== false,
-  };
-}
-
-function buildMessage({
-  sessionId,
-  trigger,
-  role = 'system',
-  visibility = 'both',
-  templateRef = null,
-  text = null,
-  metadata = {},
-}) {
-  return {
-    sessionId,
-    trigger,
-    role,
-    visibility,
-    templateRef,
-    text,
-    metadata,
-  };
-}
-
-function buildGuidanceMessage({
-  kind,
-  contextKey,
-  text,
-  templateRef = null,
-  metadata = {},
-}) {
-  const normalizedText = normalizeText(text, null);
-  const normalizedContextKey = normalizeText(contextKey, null);
-  if (!normalizedText || !normalizedContextKey) return null;
-  return {
-    kind,
-    contextKey: normalizedContextKey,
-    text: normalizedText,
-    ...(templateRef ? { templateRef } : {}),
-    metadata: metadata && typeof metadata === 'object' && !Array.isArray(metadata) ? metadata : {},
-  };
-}
-
-function finalizeGuidancePayload(messages = []) {
-  const normalizedMessages = messages.filter(Boolean);
-  if (normalizedMessages.length === 0) return null;
-  return {
-    owner: 'backend',
-    messages: normalizedMessages,
-  };
-}
-
-function formatSessionOverview(detail = {}) {
-  const sessionOverview = detail.sessionOverview && typeof detail.sessionOverview === 'object'
-    ? detail.sessionOverview
-    : {};
-  const mode = normalizeText(detail.sessionMode || sessionOverview.mode, null);
-  const maxTurns = normalizeInteger(sessionOverview.maxTurns, null);
-  const parts = [];
-
-  if (mode) parts.push(`${mode} mode`);
-  if (maxTurns != null) parts.push(`max ${maxTurns} turns`);
-
-  return parts.length > 0 ? parts.join(', ') : null;
-}
-
-export function buildRaiseHandGuidance(raiseHandPolicy = {}) {
-  const mode = normalizeText(raiseHandPolicy?.mode, null);
-  if (mode === 'dual_raise_hand') {
-    return `When you are ready to conclude, include ${CLAWORLD_RAISE_HAND_DIRECTIVE} in your reply. The round closes once both agents raise hand.`;
-  }
-  if (mode === 'single_raise_hand' || mode === 'either_raise_hand') {
-    return `When you are ready to conclude, include ${CLAWORLD_RAISE_HAND_DIRECTIVE} in your reply to close the round.`;
-  }
-  return null;
-}
-
-export function buildFinalReplyWindowSystemText() {
-  return 'This is the final reply window for the current round. Reply to the peer and conclude this round in this message.';
-}
-
-export function buildInterventionMessageText(message = {}, { roundBudget = {} } = {}) {
-  const explicitText = normalizeText(message.text, null);
-  const templateRef = normalizeText(message.templateRef, null);
-
-  if (templateRef === DEFAULT_TEMPLATE_REFS.convergence) {
-    const baseText = explicitText || 'You are near the end of this round. Focus on unresolved blockers and prepare to conclude soon.';
-    return roundBudget.finalReplyWindow
-      ? `${baseText} ${buildFinalReplyWindowSystemText()}`
-      : baseText;
-  }
-  if (explicitText) return explicitText;
-  if (templateRef === 'world.turn.nudge') {
-    return 'Stay concise. Ask only the next most useful question and move toward a decision.';
-  }
-  if (templateRef === DEFAULT_TEMPLATE_REFS.stateChanged) {
-    return 'Round state changed. Update your working state before sending anything else.';
-  }
-
-  return null;
-}
-
-export function buildRoundClosingSystemText({ continuation = {}, raiseHandPolicy = null } = {}) {
-  if (continuation?.allowed !== false) return null;
-  const reason = normalizeText(continuation.reason, null);
-  const baseText = reason === 'max_turns_reached'
-    ? 'This round closes now because the configured max-turn limit has been reached.'
-    : reason === 'dual_raise_hand'
-      ? 'This round closes now because both agents raised hand.'
-      : reason === 'raise_hand'
-        ? 'This round closes now because a completion signal was received.'
-        : 'This round closes now.';
-  const raiseHandDirective = buildRaiseHandGuidance(raiseHandPolicy);
-  return [
-    baseText,
-    'Read the message above, update your state, and do not send another relay turn.',
-    raiseHandDirective && reason !== 'dual_raise_hand' ? raiseHandDirective : null,
-  ].filter(Boolean).join(' ');
-}
-
-export function buildWorldSessionStartupEvent(detail = {}) {
-  const worldId = normalizeText(detail.worldId || detail.worldId, null);
-  if (!worldId) return null;
-  const startupText = normalizeText(detail.runtimeStartupContext?.text, null);
-  if (startupText) return startupText;
-
-  const displayName = normalizeText(detail.displayName || detail.worldDisplayName, worldId);
-  const summary = normalizeText(detail.summary, null);
-  const sessionSummary = formatSessionOverview(detail);
-  const sessionOverview = detail.sessionOverview && typeof detail.sessionOverview === 'object'
-    ? detail.sessionOverview
-    : {};
-  const raiseHandSummary = normalizeText(sessionOverview.raiseHandPolicy?.summary, null);
-  const openingText = normalizeText(sessionOverview.openingText, null);
-  const convergenceText = normalizeText(sessionOverview.convergence?.text, null);
-  const raiseHandDirective = buildRaiseHandGuidance(sessionOverview.raiseHandPolicy);
-  const interactionRules = normalizeText(detail.interactionRules, null);
-  const prohibitedRules = normalizeText(detail.prohibitedRules, null);
-  const ratingRules = normalizeText(detail.ratingRules, null);
-
-  const lines = [
-    'Internal Claworld world context for this session.',
-    'Do not acknowledge, paraphrase, or announce this setup to the peer unless it is directly relevant to their message.',
-    `World: ${displayName} [${worldId}]`,
-    summary ? `Summary: ${summary}` : null,
-    sessionSummary ? `Session overview: ${sessionSummary}` : null,
-    raiseHandSummary ? `Completion rule: ${raiseHandSummary}` : null,
-    'Interruption handling: prefer reconnect/resume. Temporary silence or reconnect churn is not the normal way to close a round.',
-    openingText ? `Opening focus: ${openingText}` : null,
-    interactionRules ? `Interaction rules: ${interactionRules}` : null,
-    prohibitedRules ? `Prohibited rules: ${prohibitedRules}` : null,
-    ratingRules ? `Rating rules: ${ratingRules}` : null,
-    convergenceText ? `Convergence rule: ${convergenceText}` : null,
-    raiseHandDirective ? `Completion signal: ${raiseHandDirective}` : null,
-    'Apply these world rules symmetrically when responding in this session.',
-  ].filter(Boolean);
-
-  return lines.join('\n');
-}
-
-export function createSystemMessageOrchestrator({ templateRefs = DEFAULT_TEMPLATE_REFS } = {}) {
-  return {
-    supportedTriggers: ['session_started', 'turn_threshold', 'convergence', 'state_changed'],
-    describeRuleShape() {
-      return {
-        opening_system_message: 'optional text/template ref',
-        turn_message_rules: [
-          {
-            id: 'turn_nudge_2',
-            trigger: 'turn_threshold',
-            atTurn: 2,
-            visibility: 'both',
-            role: 'system',
-            templateRef: 'world.turn.nudge',
-            once: true,
-          },
-        ],
-        convergence_message: {
-          whenRemainingTurnsLTE: 1,
-          templateRef: templateRefs.convergence,
-        },
-        state_change_messages: {
-          active_to_review: templateRefs.stateChanged,
-        },
-      };
-    },
-    planMessages({
-      sessionId,
-      trigger = 'session_started',
-      turnIndex = 0,
-      remainingTurns = null,
-      worldRules = {},
-      previousState = null,
-      nextState = null,
-      emittedRuleIds = [],
-    } = {}) {
-      const messages = [];
-      const emitted = new Set(emittedRuleIds);
-
-      if (trigger === 'session_started' && worldRules.openingSystemMessage !== false) {
-        messages.push(
-          buildMessage({
-            sessionId,
-            trigger,
-            templateRef: worldRules.openingTemplateRef || templateRefs.opening,
-            text: worldRules.openingText || null,
-            metadata: { phase: 'opening' },
-          }),
-        );
-      }
-
-      const rules = Array.isArray(worldRules.turnMessageRules)
-        ? worldRules.turnMessageRules.map((rule, index) => normalizeTurnRule(rule, index))
-        : [];
-      if (trigger === 'turn_threshold') {
-        for (const rule of rules) {
-          if (rule.trigger !== 'turn_threshold') continue;
-          if (rule.atTurn == null || turnIndex < rule.atTurn) continue;
-          if (rule.once && emitted.has(rule.id)) continue;
-          messages.push(
-            buildMessage({
-              sessionId,
-              trigger,
-              role: rule.role,
-              visibility: rule.visibility,
-              templateRef: rule.templateRef,
-              text: rule.text,
-              metadata: { ruleId: rule.id, atTurn: rule.atTurn },
-            }),
-          );
-          emitted.add(rule.id);
-        }
-      }
-
-      const convergenceThreshold = Number.isFinite(Number(worldRules.convergence?.whenRemainingTurnsLTE))
-        ? Number(worldRules.convergence.whenRemainingTurnsLTE)
-        : 1;
-      if (
-        trigger === 'convergence' &&
-        remainingTurns != null &&
-        Number(remainingTurns) <= convergenceThreshold
-      ) {
-        messages.push(
-          buildMessage({
-            sessionId,
-            trigger,
-            templateRef: worldRules.convergence?.templateRef || templateRefs.convergence,
-            text: worldRules.convergence?.text || null,
-            metadata: { remainingTurns: Number(remainingTurns) },
-          }),
-        );
-      }
-
-      if (trigger === 'state_changed' && previousState !== nextState && nextState) {
-        const stateKey = `${previousState || 'unknown'}_to_${nextState}`;
-        messages.push(
-          buildMessage({
-            sessionId,
-            trigger,
-            templateRef:
-              worldRules.stateChangeMessages?.[stateKey]?.templateRef || templateRefs.stateChanged,
-            text: worldRules.stateChangeMessages?.[stateKey]?.text || null,
-            metadata: {
-              previousState,
-              nextState,
-              stateKey,
-            },
-          }),
-        );
-      }
-
-      return {
-        sessionId,
-        turnIndex,
-        trigger,
-        emittedRuleIds: [...emitted],
-        messages,
-        status: messages.length > 0 ? 'planned' : 'noop',
-      };
-    },
-  };
-}
-
-export function buildSessionGuidancePayload({ session = {} } = {}) {
-  const worldContext = session?.metadata?.worldContext;
-  if (!worldContext || typeof worldContext !== 'object' || Array.isArray(worldContext)) return null;
-
-  const worldId = normalizeText(worldContext.worldId, null);
-  const startupText = buildWorldSessionStartupEvent(worldContext);
-  return finalizeGuidancePayload([
-    buildGuidanceMessage({
-      kind: 'world_session_startup',
-      contextKey: `claworld:world-startup:${normalizeText(session.sessionId, 'session')}:${worldId || 'world'}`,
-      text: startupText,
-      templateRef: DEFAULT_TEMPLATE_REFS.opening,
-      metadata: {
-        worldId,
-        sessionId: normalizeText(session.sessionId, null),
-      },
-    }),
-  ]);
-}
-
-export function buildTurnGuidancePayload({
-  session = {},
-  round = {},
-  turn = {},
-  roundBudget = {},
-  continuation = {},
-} = {}) {
-  const sessionId = normalizeText(session.sessionId, null);
-  const turnId = normalizeText(turn.turnId, 'turn');
-  const roundId = normalizeText(round.roundId || turn.roundId, 'roundless');
-  if (!sessionId) return null;
-
-  const messages = [];
-  const worldContext = session?.metadata?.worldContext;
-  const sessionOverview = worldContext?.sessionOverview && typeof worldContext.sessionOverview === 'object'
-    ? worldContext.sessionOverview
-    : {};
-  const turnRules = Array.isArray(sessionOverview.turnMessageRules)
-    ? sessionOverview.turnMessageRules.map((rule, index) => normalizeTurnRule(rule, index))
-    : [];
-  const roundTurnIndex = normalizePositiveInteger(roundBudget.roundTurnIndex, 0);
-
-  for (const rule of turnRules) {
-    if (rule.trigger !== 'turn_threshold') continue;
-    if (rule.atTurn == null || roundTurnIndex !== rule.atTurn) continue;
-    const text = buildInterventionMessageText(rule, { roundBudget });
-    messages.push(
-      buildGuidanceMessage({
-        kind: 'world_turn_threshold',
-        contextKey: `claworld:turn-guidance:${sessionId}:${turnId}:${rule.id}`,
-        text,
-        templateRef: rule.templateRef,
-        metadata: {
-          ruleId: rule.id,
-          atTurn: rule.atTurn,
-          roundId,
-        },
-      }),
-    );
-  }
-
-  const remainingTurns = normalizeInteger(roundBudget.remainingTurns, null);
-  const convergenceThreshold = normalizePositiveInteger(sessionOverview.convergence?.whenRemainingTurnsLTE, 1);
-  if (remainingTurns != null && remainingTurns <= convergenceThreshold && worldContext) {
-    const templateRef = normalizeText(sessionOverview.convergence?.templateRef, DEFAULT_TEMPLATE_REFS.convergence);
-    const text = buildInterventionMessageText(
-      {
-        templateRef,
-        text: sessionOverview.convergence?.text || null,
-      },
-      { roundBudget },
-    );
-    messages.push(
-      buildGuidanceMessage({
-        kind: 'world_convergence',
-        contextKey: `claworld:turn-guidance:${sessionId}:${turnId}:${templateRef}`,
-        text,
-        templateRef,
-        metadata: {
-          remainingTurns,
-          roundId,
-        },
-      }),
-    );
-  }
-
-  if (
-    continuation?.allowed !== false
-    && roundBudget?.hasExplicitBudget === true
-    && roundBudget?.finalReplyWindow === true
-    && messages.length === 0
-  ) {
-    messages.push(
-      buildGuidanceMessage({
-        kind: 'final_reply_window',
-        contextKey: `claworld:final-reply:${sessionId}:${turnId}`,
-        text: buildFinalReplyWindowSystemText(),
-        metadata: {
-          roundId,
-        },
-      }),
-    );
-  }
-
-  if (
-    !worldContext
-    && continuation?.allowed !== false
-    && roundTurnIndex === 1
-    && roundBudget?.raiseHandPolicy
-  ) {
-    messages.push(
-      buildGuidanceMessage({
-        kind: 'direct_round_opening',
-        contextKey: `claworld:direct-round-guidance:${sessionId}:${roundId}`,
-        text: buildRaiseHandGuidance(roundBudget.raiseHandPolicy),
-        metadata: {
-          roundId,
-        },
-      }),
-    );
-  }
-
-  messages.push(
-    buildGuidanceMessage({
-      kind: 'round_closure',
-      contextKey: `claworld:round-closure:${sessionId}:${turnId}:${normalizeText(continuation?.reason, 'complete')}`,
-      text: buildRoundClosingSystemText({
-        continuation,
-        raiseHandPolicy: roundBudget?.raiseHandPolicy || sessionOverview.raiseHandPolicy || null,
-      }),
-      metadata: {
-        reason: normalizeText(continuation?.reason, null),
-        roundId,
-      },
-    }),
-  );
-
-  return finalizeGuidancePayload(messages);
-}

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

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

package/src/product-shell/orchestration/session-orchestrator.js

@@ -1,38 +0,0 @@
-import { createSystemMessageOrchestrator } from '../../lib/runtime-guidance.js';
-
-export function createSessionOrchestrator({
-  worldService,
-  resultService,
-  systemMessages = createSystemMessageOrchestrator(),
-} = {}) {
-  return {
-    previewSession({ worldId, sessionId = 'ses_preview' } = {}) {
-      const world = worldService.requireWorld(worldId);
-      const openingPlan = systemMessages.planMessages({
-        sessionId,
-        trigger: 'session_started',
-        worldRules: world.sessionTemplate.worldRules,
-      });
-      const convergencePlan = systemMessages.planMessages({
-        sessionId,
-        trigger: 'convergence',
-        remainingTurns: Math.max(world.sessionTemplate.maxTurns - 1, 0),
-        worldRules: world.sessionTemplate.worldRules,
-      });
-
-      return {
-        worldId: world.worldId,
-        sessionTemplate: {
-          mode: world.sessionTemplate.mode,
-          maxTurns: world.sessionTemplate.maxTurns,
-          turnTimeoutMs: world.sessionTemplate.turnTimeoutMs,
-          raiseHandPolicy: world.sessionTemplate.raiseHandPolicy,
-        },
-        openingPlan,
-        convergencePlan,
-        resultPreview: resultService.preview({ world, sessionId }),
-        status: 'preview_ready',
-      };
-    },
-  };
-}