@xfxstudio/claworld 0.1.4 → 0.2.0

package/src/openclaw/plugin/relay-client.js

@@ -5,6 +5,7 @@ import { buildRuntimeAuthHeaders } from './account-identity.js';
 import { createRelayEventProtocol } from '../protocol/relay-event-protocol.js';
 import { createInboundSessionRouter } from '../runtime/inbound-session-router.js';
 import { createOutboundSessionBridge } from '../runtime/outbound-session-bridge.js';
+import { normalizeChatRequestInput } from '../../lib/chat-request.js';
 import {
   buildPublicErrorPayload,
   createRuntimeBoundaryError,
@@ -33,61 +34,19 @@ function normalizeRelayWebSocketUrl(serverUrl) {
 
 function buildInboundEnvelope(message = {}) {
   const data = message.data || {};
-  const sessionId = data.sessionId || data.requestId || null;
-  const eventId = data.turnId || data.requestId || data.sessionId || null;
-
-  switch (message.event) {
-    case 'request.received':
-      return {
-        session_id: sessionId,
-        event_id: eventId,
-        from_agent_id: data.fromAgentId || data.fromAgent?.agentId || null,
-        type: 'system_message',
-        payload: { kind: 'request.received', ...data },
-      };
-    case 'session.created':
-      return {
-        session_id: sessionId,
-        event_id: eventId,
-        from_agent_id: data.fromAgentId || data.targetAgentId || null,
-        type: 'system_message',
-        payload: { kind: 'session.created', ...data },
-      };
-    case 'turn.deliver':
-      return {
-        session_id: sessionId,
-        event_id: eventId,
-        from_agent_id: data.fromAgentId || data.fromAgent?.agentId || null,
-        type: 'message',
-        payload: data.payload || {},
-      };
-    case 'turn.reply':
-      return {
-        session_id: sessionId,
-        event_id: eventId,
-        from_agent_id: data.fromAgentId || data.fromAgent?.agentId || null,
-        type: 'message',
-        payload: data.payload || {},
-      };
-    case 'turn.timeout':
-      return {
-        session_id: sessionId,
-        event_id: eventId,
-        from_agent_id: data.fromAgentId || null,
-        type: 'system_message',
-        payload: { kind: 'turn.timeout', ...data },
-      };
-    case 'session.terminated':
-      return {
-        session_id: sessionId,
-        event_id: eventId,
-        from_agent_id: data.actorAgentId || null,
-        type: 'session_end',
-        payload: { kind: 'session.terminated', ...data },
-      };
-    default:
-      return null;
-  }
+  if (message.event !== 'delivery') return null;
+  const metadata = data.metadata && typeof data.metadata === 'object' && !Array.isArray(data.metadata)
+    ? { ...data.metadata }
+    : {};
+  return {
+    eventType: data.eventType || 'delivery',
+    deliveryId: data.deliveryId || null,
+    sessionKey: data.sessionKey || null,
+    payload: data.payload && typeof data.payload === 'object' && !Array.isArray(data.payload)
+      ? { ...data.payload }
+      : {},
+    metadata,
+  };
 }
 
 export class ClaworldRelayClient extends EventEmitter {
@@ -118,6 +77,7 @@ export class ClaworldRelayClient extends EventEmitter {
     this.reconnectAttempts = 0;
     this.manualClose = false;
     this.lastDisconnectInfo = null;
+    this.acceptedChatRequests = new Map();
   }
 
   buildBoundaryContext(extra = null) {
@@ -176,9 +136,9 @@ export class ClaworldRelayClient extends EventEmitter {
       fallbackTarget: fallbackTarget || this.runtimeConfig.routing.fallbackTarget,
     });
     const runtimeEvent = {
-      relayEvent: message.event,
+      eventType: inboundEnvelope.eventType,
       protocol: described,
-      inboundEnvelope,
+      delivery: inboundEnvelope,
       route,
       raw: message,
     };
@@ -325,12 +285,14 @@ export class ClaworldRelayClient extends EventEmitter {
           accountId: this.runtimeConfig.accountId,
           agentId,
           clientVersion,
+          bridgeProtocol: this.protocol.version,
         });
         this.send({
           type: 'auth',
           agentId,
           credential,
           clientVersion,
+          bridgeProtocol: this.protocol.version,
         });
       });
 
@@ -517,7 +479,7 @@ export class ClaworldRelayClient extends EventEmitter {
     config,
     agentId,
     credential = null,
-    clientVersion = 'claworld-plugin/0.1.4',
+    clientVersion = 'claworld-plugin/0.1.5',
     sessionTarget,
     fallbackTarget,
   } = {}) {
@@ -608,47 +570,84 @@ export class ClaworldRelayClient extends EventEmitter {
     this.send({ type: 'heartbeat' });
   }
 
-  sendTurnReply({ sessionId, messageId = null, replyText, source = 'subagent', control = null } = {}) {
-    const envelope = this.outbound.createReplyEnvelope({ sessionId, messageId, replyText, source, control });
+  sendReply({ deliveryId, sessionKey, replyText, source = 'subagent' } = {}) {
+    const envelope = this.outbound.createReplyEnvelope({
+      deliveryId,
+      sessionKey,
+      replyText,
+      source,
+    });
     this.send({
-      type: 'turn.reply',
-      sessionId,
+      type: 'reply',
+      deliveryId: envelope.deliveryId,
+      sessionKey: envelope.sessionKey,
       payload: {
-        text: envelope.reply_text,
-        source: envelope.source,
-        trace: envelope.trace,
-        ...(envelope.control ? { control: envelope.control } : {}),
+        ...envelope.payload,
       },
     });
     return envelope;
   }
 
-  terminateSession({ sessionId, reason = 'client_terminate' } = {}) {
-    this.send({ type: 'session.terminate', sessionId, reason });
+  replyToDelivery({ deliveryId, sessionKey, replyText, source = 'subagent' } = {}) {
+    return this.sendReply({
+      deliveryId,
+      sessionKey,
+      replyText,
+      source,
+    });
   }
 
-  async createSessionRequest({ fromAgentId, toAddress, requestContext = {} } = {}) {
-    return await this.requestJson('/v1/session-requests', {
+  async createChatRequest({ fromAgentId, toAddress, requestContext = {} } = {}) {
+    const target = await this.requestJson(`/v1/agents/resolve?address=${encodeURIComponent(toAddress)}`, {
+      method: 'GET',
+      headers: buildRuntimeAuthHeaders(this.runtimeConfig),
+    }, {
+      code: 'relay_target_resolve_failed',
+      message: 'failed to resolve relay target',
+      publicMessage: 'failed to resolve relay target',
+    });
+    if (target.status >= 400) return target;
+
+    const normalized = normalizeChatRequestInput({ requestContext, source: 'direct_lookup' });
+    return await this.requestJson('/v1/chat-requests', {
       method: 'POST',
       headers: buildRuntimeAuthHeaders(this.runtimeConfig, { 'content-type': 'application/json' }),
-      body: JSON.stringify({ fromAgentId, toAddress, requestContext }),
+      body: JSON.stringify({
+        fromAgentId,
+        targetAgentId: target.body?.agentId || target.body?.id || null,
+        kickoffBrief: normalized.kickoffBrief || null,
+        openingMessage: normalized.openingMessage || null,
+        worldId: normalized.conversation?.worldId || null,
+      }),
     }, {
       code: 'relay_request_create_failed',
-      message: 'failed to create relay session request',
-      publicMessage: 'failed to create relay session request',
+      message: 'failed to create relay chat request',
+      publicMessage: 'failed to create relay chat request',
     });
   }
 
-  async acceptSessionRequest(requestId, { actorAgentId, ...options } = {}) {
-    return await this.requestJson(`/v1/session-requests/${requestId}/accept`, {
+  async acceptChatRequest(requestId, { actorAgentId, ...options } = {}) {
+    const result = await this.requestJson(`/v1/chat-requests/${requestId}/accept`, {
       method: 'POST',
       headers: buildRuntimeAuthHeaders(this.runtimeConfig, { 'content-type': 'application/json' }),
       body: JSON.stringify({ actorAgentId, ...options }),
     }, {
       code: 'relay_request_accept_failed',
-      message: 'failed to accept relay session request',
-      publicMessage: 'failed to accept relay session request',
+      message: 'failed to accept relay chat request',
+      publicMessage: 'failed to accept relay chat request',
     });
+    if (result.status < 400 && requestId) {
+      const kickoff = result.body?.kickoff && typeof result.body.kickoff === 'object' && !Array.isArray(result.body.kickoff)
+        ? { ...result.body.kickoff }
+        : null;
+      this.acceptedChatRequests.set(requestId, {
+        requestId,
+        sessionKey: kickoff?.sessionKey || null,
+        conversationKey: kickoff?.conversationKey || null,
+        kickoff,
+      });
+    }
+    return result;
   }
 
   async deliverMessage({ fromAgentId, toAddress, payload = {}, conversation = {} } = {}) {
@@ -663,18 +662,6 @@ export class ClaworldRelayClient extends EventEmitter {
     });
   }
 
-  async createTurn({ sessionId, fromAgentId, payload = {} } = {}) {
-    return await this.requestJson(`/v1/sessions/${sessionId}/turns`, {
-      method: 'POST',
-      headers: buildRuntimeAuthHeaders(this.runtimeConfig, { 'content-type': 'application/json' }),
-      body: JSON.stringify({ fromAgentId, payload }),
-    }, {
-      code: 'relay_turn_create_failed',
-      message: 'failed to create relay turn',
-      publicMessage: 'failed to create relay turn',
-    });
-  }
-
   waitFor(eventNameOrPredicate, timeoutMs = 8000) {
     const isPredicate = typeof eventNameOrPredicate === 'function';
     const predicate = isPredicate
@@ -700,7 +687,7 @@ export class ClaworldRelayClient extends EventEmitter {
     });
   }
 
-  async establishSession({ fromAgentId, toAddress, requestContext = {}, openingPayload = {} } = {}) {
+  async establishConversation({ fromAgentId, toAddress, requestContext = {}, openingPayload = {} } = {}) {
     const normalizedRequestContext = requestContext && typeof requestContext === 'object' && !Array.isArray(requestContext)
       ? { ...requestContext }
       : {};
@@ -714,32 +701,55 @@ export class ClaworldRelayClient extends EventEmitter {
       }
     }
 
-    const requestResult = await this.createSessionRequest({
+    const requestResult = await this.createChatRequest({
       fromAgentId,
       toAddress,
       requestContext: normalizedRequestContext,
     });
     if (requestResult.status !== 201) {
-      throw new Error(`failed to create session request: ${JSON.stringify(requestResult.body)}`);
+      throw new Error(`failed to create chat request: ${JSON.stringify(requestResult.body)}`);
     }
     const requestId = requestResult.body.requestId;
     return {
       requestId,
-      sessionId: null,
-      openApprovedSession: async ({ timeoutMs = 15000 } = {}) => {
-        const acceptedEvent = await this.waitFor(
-          (event) => event.event === 'request.updated'
-            && event.data?.requestId === requestId
-            && event.data?.status === 'accepted',
+      sessionKey: null,
+      conversationKey: null,
+      openAcceptedConversation: async ({ timeoutMs = 15000 } = {}) => {
+        const acceptedRequest = this.acceptedChatRequests.get(requestId) || null;
+        if (acceptedRequest?.kickoff || acceptedRequest?.conversationKey || acceptedRequest?.sessionKey) {
+          return {
+            requestId,
+            sessionKey: acceptedRequest?.sessionKey || acceptedRequest?.kickoff?.sessionKey || null,
+            conversationKey: acceptedRequest?.conversationKey || acceptedRequest?.kickoff?.conversationKey || null,
+            kickoff: acceptedRequest?.kickoff || null,
+            delivery: null,
+          };
+        }
+        const deliveryEvent = await this.waitFor(
+          (event) => event.event === 'delivery'
+            && (
+              event.data?.metadata?.kickoffRequestId === requestId
+            ),
           timeoutMs,
         );
-        const kickoff = acceptedEvent?.data?.kickoff && typeof acceptedEvent.data.kickoff === 'object'
-          ? acceptedEvent.data.kickoff
-          : null;
+        const delivery = deliveryEvent?.data && typeof deliveryEvent.data === 'object' && !Array.isArray(deliveryEvent.data)
+          ? deliveryEvent.data
+          : {};
+        const metadata = delivery.metadata && typeof delivery.metadata === 'object' && !Array.isArray(delivery.metadata)
+          ? delivery.metadata
+          : {};
+        const kickoff = {
+          status: 'delivered',
+          deliveryId: delivery.deliveryId || null,
+          sessionKey: delivery.sessionKey || metadata.sessionKey || null,
+          conversationKey: delivery.conversationKey || null,
+        };
         return {
           requestId,
-          sessionId: kickoff?.sessionId || null,
+          sessionKey: kickoff.sessionKey,
+          conversationKey: kickoff.conversationKey,
           kickoff,
+          delivery: deliveryEvent,
         };
       },
     };

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

@@ -1,31 +1,43 @@
-const MINIMAL_EVENT_TYPES = [
-  'message',
-  'raise_hand',
-  'session_end',
-  'session_result_ready',
-  'system_message',
-  'ack',
-];
+export const CLAWORLD_PLUGIN_BRIDGE_PROTOCOL = 'claworld.delivery_reply.v1';
+
+const DELIVERY_EVENT_TYPE = 'delivery';
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function normalizePayload(payload = null) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return {};
+  return { ...payload };
+}
 
 export function createRelayEventProtocol() {
   return {
-    version: 'claworld.a2a.v0.scaffold',
-    requiredEnvelopeFields: ['event_id', 'session_id', 'type', 'payload', 'ts'],
-    eventTypes: MINIMAL_EVENT_TYPES,
+    version: CLAWORLD_PLUGIN_BRIDGE_PROTOCOL,
+    eventTypes: [DELIVERY_EVENT_TYPE],
+    requiredEnvelopeFields: ['eventType', 'deliveryId', 'sessionKey', 'payload'],
     describeEvent(event = {}) {
+      const payload = normalizePayload(event.payload);
+      const missing = [];
+      if (normalizeText(event.eventType, null) !== DELIVERY_EVENT_TYPE) {
+        missing.push('eventType');
+      }
+      if (!normalizeText(event.deliveryId, null)) {
+        missing.push('deliveryId');
+      }
+      if (!normalizeText(event.sessionKey, null)) {
+        missing.push('sessionKey');
+      }
+      if (!normalizeText(payload.text, null)) {
+        missing.push('payload.text');
+      }
       return {
-        ok: MINIMAL_EVENT_TYPES.includes(event.type),
-        missing: this.requiredEnvelopeFields.filter((field) => event[field] == null),
-        role: event.role || inferRoleFromType(event.type),
+        ok: missing.length === 0,
+        missing,
+        role: 'delivery',
       };
     },
   };
 }
-
-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

@@ -34,12 +34,16 @@ function buildSummary({ matchScore, riskCount, intentCount, conversationCount, a
 }
 
 function pickRecommendation({ matchScore, normalizedSignals, risks }) {
-  const raisedHands = normalizedSignals.filter((signal) => signal.type === 'raise_hand').length;
+  const readySignals = normalizedSignals.filter(
+    (signal) => signal.type === 'next_step_ready'
+      || signal.type === 'human_handoff_ready'
+      || signal.type === 'conversation_complete',
+  ).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) {
+  if (readySignals >= 2 && (matchScore == null || matchScore >= 0.45) && risks.length <= 1) {
     return 'continue';
   }
   if (matchScore != null && matchScore >= 0.65 && risks.length === 0) {
@@ -58,9 +62,15 @@ export function createCanonicalResultBuilder() {
       summary: 'string',
       risks: 'string[]',
       recommendation: 'continue|pass|review',
-      evidence: 'SessionMessage[]',
+      evidence: 'ConversationMessage[]',
     },
-    build({ sessionId, intentSignals = [], conversationSignals = [], agentSignals = [] } = {}) {
+    build({
+      conversationId = null,
+      intentSignals = [],
+      conversationSignals = [],
+      agentSignals = [],
+    } = {}) {
+      const resolvedConversationId = conversationId || null;
       const normalizedIntentSignals = intentSignals.map((signal, index) =>
         normalizeSignal(signal, index, 'intent'),
       );
@@ -92,7 +102,7 @@ export function createCanonicalResultBuilder() {
         }));
 
       return {
-        sessionId,
+        conversationId: resolvedConversationId,
         match_score: matchScore,
         summary: buildSummary({
           matchScore,

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

@@ -4,23 +4,19 @@ export function createDemoSessionBootstrap() {
       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',

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

@@ -110,8 +110,9 @@ export async function submitFeedbackReport({
       reproductionSteps,
       context: {
         worldId: normalizeText(normalizedContext.worldId, null),
-        sessionId: normalizeText(normalizedContext.sessionId, null),
-        roundId: normalizeText(normalizedContext.roundId, null),
+        conversationKey: normalizeText(normalizedContext.conversationKey, null),
+        turnId: normalizeText(normalizedContext.turnId, null),
+        deliveryId: normalizeText(normalizedContext.deliveryId, null),
         targetAgentId: normalizeText(normalizedContext.targetAgentId, null),
         targetAgentCode: normalizeText(normalizedContext.targetAgentCode, null),
         tags: normalizeStringList(normalizedContext.tags),

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

@@ -1,35 +1,43 @@
 import { OPENCLAW_RUNTIME_PATH, createRuntimePathTrace } from './runtime-path.js';
 
-function normalizeSessionTarget(value, fallback) {
-  const candidate = typeof value === 'string' ? value.trim() : '';
-  return candidate || fallback;
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function normalizePayload(payload = null) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return {};
+  return { ...payload };
 }
 
 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;
+      const eventType = normalizeText(event.eventType || event.type, null);
+      const deliveryId = normalizeText(event.deliveryId || event.event_id || event.eventId, null);
+      const sessionKey = normalizeText(event.sessionKey, null);
+      const payload = normalizePayload(event.payload);
       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'],
+        action: 'route_delivery',
+        target: normalizeText(options.sessionTarget, 'mainagent'),
+        fallbackTarget: normalizeText(options.fallbackTarget, 'mainagent'),
+        eventType,
+        deliveryId,
+        sessionKey,
+        payload,
+        metadata: event.metadata && typeof event.metadata === 'object' && !Array.isArray(event.metadata)
+          ? { ...event.metadata }
+          : {},
         trace: createRuntimePathTrace({
-          sessionId: event.session_id || null,
-          eventId: event.event_id || null,
+          sessionKey,
+          eventId: deliveryId,
           direction: 'inbound',
         }),
-        status: route?.sessionKey ? 'resolved' : 'unresolved',
+        status: eventType === 'delivery' && deliveryId && sessionKey && normalizeText(payload.text, null)
+          ? 'resolved'
+          : 'invalid',
       };
     },
   };

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

@@ -1,16 +1,28 @@
-import { createRuntimePathTrace } from './runtime-path.js';
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
 
 export function createOutboundSessionBridge() {
   return {
-    createReplyEnvelope({ sessionId, messageId = null, replyText, source = 'subagent', control = null } = {}) {
+    createReplyEnvelope({
+      deliveryId,
+      sessionKey,
+      replyText,
+      source = 'subagent',
+    } = {}) {
+      const normalizedReplyText = normalizeText(replyText, '');
+      const normalizedDeliveryId = normalizeText(deliveryId, null);
+      const normalizedSessionKey = normalizeText(sessionKey, 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',
+        eventType: 'reply',
+        deliveryId: normalizedDeliveryId,
+        sessionKey: normalizedSessionKey,
+        payload: {
+          text: normalizedReplyText,
+          source: normalizeText(source, 'subagent'),
+        },
       };
     },
   };