@xfxstudio/claworld 0.1.0

package/src/openclaw/plugin/runtime.js

@@ -0,0 +1,12 @@
+let currentRuntime = null;
+
+export function setClaworldRuntime(runtime) {
+  currentRuntime = runtime || null;
+}
+
+export function getClaworldRuntime() {
+  if (!currentRuntime) {
+    throw new Error('Claworld runtime not initialized');
+  }
+  return currentRuntime;
+}

package/src/openclaw/protocol/relay-event-protocol.js

@@ -0,0 +1,31 @@
+const MINIMAL_EVENT_TYPES = [
+  'message',
+  'raise_hand',
+  'session_end',
+  'session_result_ready',
+  'system_message',
+  'ack',
+];
+
+export function createRelayEventProtocol() {
+  return {
+    version: 'claworld.a2a.v0.scaffold',
+    requiredEnvelopeFields: ['event_id', 'session_id', 'type', 'payload', 'ts'],
+    eventTypes: MINIMAL_EVENT_TYPES,
+    describeEvent(event = {}) {
+      return {
+        ok: MINIMAL_EVENT_TYPES.includes(event.type),
+        missing: this.requiredEnvelopeFields.filter((field) => event[field] == null),
+        role: event.role || inferRoleFromType(event.type),
+      };
+    },
+  };
+}
+
+function inferRoleFromType(type) {
+  if (type === 'system_message') return 'system';
+  if (type === 'raise_hand') return 'control';
+  if (type === 'message') return 'agent';
+  if (type === 'session_result_ready') return 'system';
+  return 'control';
+}

package/src/openclaw/runtime/canonical-result-builder.js

@@ -0,0 +1,116 @@
+function normalizeSignal(signal = {}, index = 0, source = 'unknown') {
+  const score = Number.isFinite(Number(signal.score)) ? Number(signal.score) : 0;
+  const risk = Number.isFinite(Number(signal.risk)) ? Number(signal.risk) : 0;
+  return {
+    id: signal.id || `${source}_${index + 1}`,
+    type: signal.type || 'note',
+    source,
+    score,
+    risk,
+    summary: signal.summary || signal.text || signal.type || `${source} signal ${index + 1}`,
+    weight: Number.isFinite(Number(signal.weight)) ? Number(signal.weight) : 1,
+    metadata: signal.metadata || {},
+  };
+}
+
+function computeWeightedAverage(signals) {
+  if (signals.length === 0) return null;
+  const totalWeight = signals.reduce((sum, signal) => sum + signal.weight, 0);
+  if (totalWeight <= 0) return null;
+  const totalScore = signals.reduce((sum, signal) => sum + signal.score * signal.weight, 0);
+  return Number((totalScore / totalWeight).toFixed(3));
+}
+
+function collectRisks(signals) {
+  return signals
+    .filter((signal) => signal.risk > 0)
+    .sort((a, b) => b.risk - a.risk)
+    .map((signal) => signal.summary);
+}
+
+function buildSummary({ matchScore, riskCount, intentCount, conversationCount, agentCount }) {
+  const scoreText = matchScore == null ? 'insufficient evidence' : `match score ${matchScore}`;
+  return `Canonical result built from ${intentCount} intent, ${conversationCount} conversation, ${agentCount} agent signals; ${scoreText}; ${riskCount} risk signal(s).`;
+}
+
+function pickRecommendation({ matchScore, normalizedSignals, risks }) {
+  const raisedHands = normalizedSignals.filter((signal) => signal.type === 'raise_hand').length;
+  const hardBlock = normalizedSignals.some(
+    (signal) => signal.type === 'block' || signal.metadata?.hardBlock === true || signal.risk >= 0.85,
+  );
+  if (hardBlock) return 'pass';
+  if (raisedHands >= 2 && (matchScore == null || matchScore >= 0.45) && risks.length <= 1) {
+    return 'continue';
+  }
+  if (matchScore != null && matchScore >= 0.65 && risks.length === 0) {
+    return 'continue';
+  }
+  if (matchScore != null && matchScore < 0.25) {
+    return 'pass';
+  }
+  return 'review';
+}
+
+export function createCanonicalResultBuilder() {
+  return {
+    schema: {
+      match_score: 'number',
+      summary: 'string',
+      risks: 'string[]',
+      recommendation: 'continue|pass|review',
+      evidence: 'SessionMessage[]',
+    },
+    build({ sessionId, intentSignals = [], conversationSignals = [], agentSignals = [] } = {}) {
+      const normalizedIntentSignals = intentSignals.map((signal, index) =>
+        normalizeSignal(signal, index, 'intent'),
+      );
+      const normalizedConversationSignals = conversationSignals.map((signal, index) =>
+        normalizeSignal(signal, index, 'conversation'),
+      );
+      const normalizedAgentSignals = agentSignals.map((signal, index) =>
+        normalizeSignal(signal, index, 'agent'),
+      );
+      const normalizedSignals = [
+        ...normalizedIntentSignals,
+        ...normalizedConversationSignals,
+        ...normalizedAgentSignals,
+      ];
+
+      const matchScore = computeWeightedAverage(normalizedSignals);
+      const risks = collectRisks(normalizedSignals);
+      const recommendation = pickRecommendation({ matchScore, normalizedSignals, risks });
+      const evidence = normalizedSignals
+        .sort((a, b) => Math.abs(b.score) + b.risk - (Math.abs(a.score) + a.risk))
+        .slice(0, 5)
+        .map((signal) => ({
+          id: signal.id,
+          type: signal.type,
+          source: signal.source,
+          summary: signal.summary,
+          score: signal.score,
+          risk: signal.risk,
+        }));
+
+      return {
+        sessionId,
+        match_score: matchScore,
+        summary: buildSummary({
+          matchScore,
+          riskCount: risks.length,
+          intentCount: normalizedIntentSignals.length,
+          conversationCount: normalizedConversationSignals.length,
+          agentCount: normalizedAgentSignals.length,
+        }),
+        risks,
+        recommendation,
+        evidence,
+        inputs: {
+          intentSignalsCount: normalizedIntentSignals.length,
+          conversationSignalsCount: normalizedConversationSignals.length,
+          agentSignalsCount: normalizedAgentSignals.length,
+        },
+        status: 'built',
+      };
+    },
+  };
+}

package/src/openclaw/runtime/demo-session-bootstrap.js

@@ -0,0 +1,37 @@
+export function createDemoSessionBootstrap() {
+  return {
+    defaults: {
+      users: ['demo-a', 'demo-b'],
+      world: 'dating-demo-world',
+      allowDemoToken: true,
+      maxTurns: 6,
+    },
+    createLaunchPlan({
+      sessionGoal = 'run one stable A2A demo loop',
+      users,
+      world,
+      maxTurns,
+      openingMessage = 'You are entering demo mode. Try to complete one stable match loop.',
+    } = {}) {
+      const resolvedUsers = Array.isArray(users) && users.length > 0 ? users : this.defaults.users;
+      const resolvedWorld = world || this.defaults.world;
+      const resolvedMaxTurns = Number.isFinite(Number(maxTurns)) ? Number(maxTurns) : this.defaults.maxTurns;
+      return {
+        sessionGoal,
+        world: resolvedWorld,
+        users: resolvedUsers,
+        maxTurns: resolvedMaxTurns,
+        openingMessage,
+        steps: [
+          'load demo users',
+          'load demo world',
+          'create manual session',
+          'inject opening system message',
+          'wait for dual raise or manual stop',
+          'build canonical result',
+        ],
+        status: 'planned',
+      };
+    },
+  };
+}

package/src/openclaw/runtime/feedback-helper.js

@@ -0,0 +1,145 @@
+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 normalizeStringList(values = []) {
+  if (!Array.isArray(values)) return [];
+  return [...new Set(values.map((value) => normalizeText(value, null)).filter(Boolean))];
+}
+
+function normalizeObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  return value;
+}
+
+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(/\/$/, '');
+}
+
+export async function submitFeedbackReport({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  agentId = null,
+  category = null,
+  title = null,
+  goal = null,
+  actualBehavior = null,
+  expectedBehavior = null,
+  impact = null,
+  details = null,
+  reproductionSteps = [],
+  context = {},
+  fetchImpl,
+  logger = console,
+  toolCallId = null,
+  pluginVersion = null,
+  toolContractVersion = null,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for claworld feedback helper');
+  }
+
+  const resolvedAgentId = normalizeText(agentId, null);
+  if (!resolvedAgentId) {
+    throw new Error('claworld feedback helper requires agentId');
+  }
+
+  const normalizedContext = normalizeObject(context);
+  const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+  const result = await fetchJson(fetchImpl, `${baseUrl}/v1/feedback`, {
+    method: 'POST',
+    headers: buildRuntimeAuthHeaders(resolvedRuntimeConfig, {
+      accept: 'application/json',
+      'content-type': 'application/json',
+      ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+    }),
+    body: JSON.stringify({
+      agentId: resolvedAgentId,
+      accountId: normalizeText(resolvedRuntimeConfig.accountId, normalizeText(accountId, null)),
+      category,
+      title,
+      goal,
+      actualBehavior,
+      expectedBehavior,
+      impact,
+      details,
+      reproductionSteps,
+      context: {
+        worldId: normalizeText(normalizedContext.worldId, null),
+        sessionId: normalizeText(normalizedContext.sessionId, null),
+        roundId: normalizeText(normalizedContext.roundId, null),
+        targetAgentId: normalizeText(normalizedContext.targetAgentId, null),
+        targetAgentCode: normalizeText(normalizedContext.targetAgentCode, null),
+        tags: normalizeStringList(normalizedContext.tags),
+        metadata: normalizeObject(normalizedContext.metadata),
+      },
+      source: 'openclaw_tool',
+      runtimeContext: {
+        channelId: 'claworld',
+        toolName: 'claworld_submit_feedback',
+        toolCallId: normalizeText(toolCallId, null),
+        pluginVersion: normalizeText(pluginVersion, null),
+        toolContractVersion: normalizeText(toolContractVersion, null),
+        accountId: normalizeText(resolvedRuntimeConfig.accountId, normalizeText(accountId, null)),
+        serverUrl: baseUrl,
+        relayAgentId: resolvedAgentId,
+        defaultToAddress: normalizeText(resolvedRuntimeConfig.relay?.defaultToAddress, null),
+      },
+    }),
+  });
+
+  if (!result.ok) {
+    logger.error?.('[claworld:feedback] feedback submit failed', {
+      status: result.status,
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      body: result.body,
+    });
+    throw new Error(`claworld feedback submit failed: ${result.status}`);
+  }
+
+  return result.body;
+}

package/src/openclaw/runtime/inbound-session-router.js

@@ -0,0 +1,36 @@
+import { OPENCLAW_RUNTIME_PATH, createRuntimePathTrace } from './runtime-path.js';
+
+function normalizeSessionTarget(value, fallback) {
+  const candidate = typeof value === 'string' ? value.trim() : '';
+  return candidate || fallback;
+}
+
+export function createInboundSessionRouter() {
+  return {
+    runtimePath: OPENCLAW_RUNTIME_PATH,
+    routeInboundEvent(event = {}, options = {}) {
+      const target = normalizeSessionTarget(options.sessionTarget, 'subagent');
+      const fallbackTarget = normalizeSessionTarget(options.fallbackTarget, 'mainagent');
+      const route = options.route && typeof options.route === 'object' ? options.route : null;
+      return {
+        action: 'route_inbound_event',
+        target,
+        fallbackTarget,
+        sessionId: event.session_id || null,
+        eventId: event.event_id || null,
+        fromAgentId: event.from_agent_id || null,
+        eventType: event.type || null,
+        route,
+        sessionKey: route?.sessionKey || null,
+        accountId: route?.accountId || null,
+        preserveFields: ['session_id', 'event_id', 'from_agent_id'],
+        trace: createRuntimePathTrace({
+          sessionId: event.session_id || null,
+          eventId: event.event_id || null,
+          direction: 'inbound',
+        }),
+        status: route?.sessionKey ? 'resolved' : 'unresolved',
+      };
+    },
+  };
+}

package/src/openclaw/runtime/outbound-session-bridge.js

@@ -0,0 +1,17 @@
+import { createRuntimePathTrace } from './runtime-path.js';
+
+export function createOutboundSessionBridge() {
+  return {
+    createReplyEnvelope({ sessionId, messageId = null, replyText, source = 'subagent', control = null } = {}) {
+      return {
+        session_id: sessionId,
+        message_id: messageId,
+        reply_text: replyText,
+        source,
+        control: control && typeof control === 'object' && !Array.isArray(control) ? { ...control } : null,
+        trace: createRuntimePathTrace({ sessionId, eventId: messageId, direction: 'outbound' }),
+        status: 'scaffold_only',
+      };
+    },
+  };
+}