@xfxstudio/claworld 0.2.23-beta.0 → 0.2.23-beta.2

package/openclaw.plugin.json

@@ -8,7 +8,7 @@
   ],
   "name": "Claworld Persona Relay",
   "description": "Claworld relay world channel plugin for OpenClaw.",
-  "version": "0.2.23-beta.0",
+  "version": "0.2.23-beta.2",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfxstudio/claworld",
-  "version": "0.2.23-beta.0",
+  "version": "0.2.23-beta.2",
   "description": "Claworld channel plugin for OpenClaw",
   "type": "module",
   "main": "index.js",

package/src/lib/chat-request.js

@@ -1,4 +1,5 @@
 import { createKickoffBrief } from './relay/kickoff-text.js';
+import { normalizeAcceptedChatKickoffRecord } from './relay/kickoff-progress.js';
 
 function normalizeText(value, fallback = null) {
   if (value == null) return fallback;
@@ -358,7 +359,7 @@ export function normalizeStoredChatRequest(input = {}, { defaultSource = 'chat_r
   if (acceptedByAgentId) normalized.acceptedByAgentId = acceptedByAgentId;
   const approvalGrantId = normalizeText(input.approvalGrantId, null);
   if (approvalGrantId) normalized.approvalGrantId = approvalGrantId;
-  const kickoff = cloneJsonObject(input.kickoff);
+  const kickoff = normalizeAcceptedChatKickoffRecord(cloneJsonObject(input.kickoff));
   if (kickoff) normalized.kickoff = kickoff;
 
   return normalized;

package/src/lib/relay/kickoff-progress.js

@@ -0,0 +1,162 @@
+import { normalizeOptionalText } from './shared.js';
+
+function normalizeAcceptedChatKickoffField(value, fallback = null) {
+  return normalizeOptionalText(value) || fallback;
+}
+
+export function normalizeAcceptedChatKickoffRecord(kickoff = null, { fallbackStatus = null } = {}) {
+  if (!kickoff || typeof kickoff !== 'object' || Array.isArray(kickoff)) return null;
+
+  const normalized = {
+    ...kickoff,
+  };
+
+  const normalizedStatus = normalizeAcceptedChatKickoffField(normalized.status, fallbackStatus);
+  const normalizedReason = normalizeAcceptedChatKickoffField(normalized.reason, null);
+  const normalizedDeliveredAt = normalizeAcceptedChatKickoffField(normalized.deliveredAt, null);
+  const normalizedSenderKickoffDeliveredAt = normalizeAcceptedChatKickoffField(
+    normalized.senderKickoffDeliveredAt,
+    normalizedDeliveredAt,
+  );
+  const normalizedOpenerAcceptedAt = normalizeAcceptedChatKickoffField(normalized.openerAcceptedAt, null);
+  const normalizedOpenerDeliveredAt = normalizeAcceptedChatKickoffField(normalized.openerDeliveredAt, null);
+  const normalizedLiveChatEstablishedAt = normalizeAcceptedChatKickoffField(normalized.liveChatEstablishedAt, null);
+  const normalizedTurnId = normalizeAcceptedChatKickoffField(normalized.turnId, null);
+  const normalizedDeliveryId = normalizeAcceptedChatKickoffField(normalized.deliveryId, null);
+  const normalizedConversationKey = normalizeAcceptedChatKickoffField(normalized.conversationKey, null);
+  const normalizedOpenerTurnId = normalizeAcceptedChatKickoffField(normalized.openerTurnId, null);
+  const normalizedOpenerDeliveryId = normalizeAcceptedChatKickoffField(normalized.openerDeliveryId, null);
+  const normalizedFailedAt = normalizeAcceptedChatKickoffField(normalized.failedAt, null);
+
+  if (normalizedStatus) normalized.status = normalizedStatus;
+  else delete normalized.status;
+  if (normalizedReason) normalized.reason = normalizedReason;
+  else delete normalized.reason;
+  if (normalizedDeliveredAt) normalized.deliveredAt = normalizedDeliveredAt;
+  else delete normalized.deliveredAt;
+  if (normalizedSenderKickoffDeliveredAt) normalized.senderKickoffDeliveredAt = normalizedSenderKickoffDeliveredAt;
+  else delete normalized.senderKickoffDeliveredAt;
+  if (normalizedOpenerAcceptedAt) normalized.openerAcceptedAt = normalizedOpenerAcceptedAt;
+  else delete normalized.openerAcceptedAt;
+  if (normalizedOpenerDeliveredAt) normalized.openerDeliveredAt = normalizedOpenerDeliveredAt;
+  else delete normalized.openerDeliveredAt;
+  if (normalizedLiveChatEstablishedAt) normalized.liveChatEstablishedAt = normalizedLiveChatEstablishedAt;
+  else delete normalized.liveChatEstablishedAt;
+  if (normalizedTurnId) normalized.turnId = normalizedTurnId;
+  else delete normalized.turnId;
+  if (normalizedDeliveryId) normalized.deliveryId = normalizedDeliveryId;
+  else delete normalized.deliveryId;
+  if (normalizedConversationKey) normalized.conversationKey = normalizedConversationKey;
+  else delete normalized.conversationKey;
+  if (normalizedOpenerTurnId) normalized.openerTurnId = normalizedOpenerTurnId;
+  else delete normalized.openerTurnId;
+  if (normalizedOpenerDeliveryId) normalized.openerDeliveryId = normalizedOpenerDeliveryId;
+  else delete normalized.openerDeliveryId;
+  if (normalizedFailedAt) normalized.failedAt = normalizedFailedAt;
+  else delete normalized.failedAt;
+
+  const hasEstablishedEvidence = Boolean(
+    normalized.openerDeliveredAt
+    || normalized.liveChatEstablishedAt,
+  );
+
+  if (hasEstablishedEvidence && (!normalized.status || ['queued', 'sent'].includes(normalized.status))) {
+    normalized.status = 'established';
+  }
+
+  if (normalized.status === 'established') {
+    const establishedAt = normalizeAcceptedChatKickoffField(
+      normalized.liveChatEstablishedAt,
+      normalizeAcceptedChatKickoffField(
+        normalized.openerDeliveredAt,
+        normalizeAcceptedChatKickoffField(normalized.openerAcceptedAt, null),
+      ),
+    );
+    if (!normalized.openerDeliveredAt && normalized.openerAcceptedAt) {
+      normalized.openerDeliveredAt = normalized.openerAcceptedAt;
+    }
+    if (!normalized.liveChatEstablishedAt && establishedAt) {
+      normalized.liveChatEstablishedAt = establishedAt;
+    }
+    if (String(normalized.reason || '').startsWith('queued_')) {
+      delete normalized.reason;
+    }
+  }
+
+  return normalized;
+}
+
+export async function markAcceptedChatKickoffFailureWithDeps(deps, {
+  requestId = null,
+  reason = 'accepted_chat_kickoff_failed',
+  turnId = null,
+  conversationKey = null,
+} = {}) {
+  const { store, pushToAgent } = deps;
+  const normalizedRequestId = normalizeOptionalText(requestId);
+  if (!normalizedRequestId) return null;
+  const request = store.getChatRequest(normalizedRequestId);
+  if (!request) return null;
+
+  request.kickoff = normalizeAcceptedChatKickoffRecord({
+    ...(request.kickoff && typeof request.kickoff === 'object' && !Array.isArray(request.kickoff) ? request.kickoff : {}),
+    status: 'failed',
+    reason: normalizeOptionalText(reason) || 'accepted_chat_kickoff_failed',
+    ...(normalizeOptionalText(turnId) ? { turnId: normalizeOptionalText(turnId) } : {}),
+    ...(normalizeOptionalText(conversationKey) ? { conversationKey: normalizeOptionalText(conversationKey) } : {}),
+    failedAt: store.now(),
+  });
+  if (store.markChatRequestUpdated) {
+    await store.markChatRequestUpdated();
+  }
+  await pushToAgent(request.fromAgentId, 'request.updated', request);
+  await pushToAgent(request.toAgentId, 'request.updated', request);
+  return request;
+}
+
+export async function markAcceptedChatKickoffProgressWithDeps(deps, {
+  requestId = null,
+  status = null,
+  reason = null,
+  turnId = null,
+  deliveryId = null,
+  conversationKey = null,
+  senderKickoffDeliveredAt = null,
+  openerAcceptedAt = null,
+  openerDeliveredAt = null,
+  liveChatEstablishedAt = null,
+  openerTurnId = null,
+  openerDeliveryId = null,
+} = {}) {
+  const { store, pushToAgent } = deps;
+  const normalizedRequestId = normalizeOptionalText(requestId);
+  if (!normalizedRequestId) return null;
+  const request = store.getChatRequest(normalizedRequestId);
+  if (!request) return null;
+
+  request.kickoff = normalizeAcceptedChatKickoffRecord({
+    ...(request.kickoff && typeof request.kickoff === 'object' && !Array.isArray(request.kickoff) ? request.kickoff : {}),
+    ...(normalizeOptionalText(status) ? { status: normalizeOptionalText(status) } : {}),
+    ...(normalizeOptionalText(reason) ? { reason: normalizeOptionalText(reason) } : {}),
+    ...(normalizeOptionalText(turnId) ? { turnId: normalizeOptionalText(turnId) } : {}),
+    ...(normalizeOptionalText(deliveryId) ? { deliveryId: normalizeOptionalText(deliveryId) } : {}),
+    ...(normalizeOptionalText(conversationKey) ? { conversationKey: normalizeOptionalText(conversationKey) } : {}),
+    ...(normalizeOptionalText(senderKickoffDeliveredAt)
+      ? {
+          senderKickoffDeliveredAt: normalizeOptionalText(senderKickoffDeliveredAt),
+          deliveredAt: normalizeOptionalText(senderKickoffDeliveredAt),
+        }
+      : {}),
+    ...(normalizeOptionalText(openerAcceptedAt) ? { openerAcceptedAt: normalizeOptionalText(openerAcceptedAt) } : {}),
+    ...(normalizeOptionalText(openerDeliveredAt) ? { openerDeliveredAt: normalizeOptionalText(openerDeliveredAt) } : {}),
+    ...(normalizeOptionalText(liveChatEstablishedAt) ? { liveChatEstablishedAt: normalizeOptionalText(liveChatEstablishedAt) } : {}),
+    ...(normalizeOptionalText(openerTurnId) ? { openerTurnId: normalizeOptionalText(openerTurnId) } : {}),
+    ...(normalizeOptionalText(openerDeliveryId) ? { openerDeliveryId: normalizeOptionalText(openerDeliveryId) } : {}),
+  });
+  if (store.markChatRequestUpdated) {
+    await store.markChatRequestUpdated();
+  }
+  await pushToAgent(request.fromAgentId, 'request.updated', request);
+  await pushToAgent(request.toAgentId, 'request.updated', request);
+  return request;
+}

package/src/lib/relay/shared.js

@@ -0,0 +1,30 @@
+export function normalizePositiveInteger(value, fallback) {
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized) || normalized <= 0) return fallback;
+  return Math.floor(normalized);
+}
+
+export function normalizeOptionalText(value) {
+  if (typeof value !== 'string') return null;
+  const normalized = value.trim();
+  return normalized || null;
+}
+
+export function cloneJsonObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  try {
+    const cloned = JSON.parse(JSON.stringify(value));
+    if (!cloned || typeof cloned !== 'object' || Array.isArray(cloned)) return null;
+    return cloned;
+  } catch {
+    return null;
+  }
+}
+
+export function buildFailureBody(reason, extras = {}) {
+  return {
+    error: reason,
+    reason,
+    ...extras,
+  };
+}

package/src/openclaw/plugin/claworld-channel-plugin.js

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import claworldPackageJson from '../../../package.json' with { type: 'json' };
 
 import {
   applyRuntimeIdentity,
@@ -57,6 +58,8 @@ import {
 } from '../../lib/runtime-errors.js';
 import { PUBLIC_IDENTITY_STATUS } from '../../lib/public-identity.js';
 
+const CLAWORLD_PLUGIN_VERSION = claworldPackageJson.version;
+
 function normalizeRelayHttpBaseUrl(serverUrl) {
   const parsed = new URL(serverUrl);
   if (parsed.protocol === 'ws:') parsed.protocol = 'http:';
@@ -174,6 +177,20 @@ const CLAWORLD_RELAY_OPERATIONAL_NOTICE_PATTERNS = [
   /^⚠️\s*Agent failed before reply:/i,
 ];
 
+// Older/runtime-variant OpenClaw hosts may surface provider/runtime failures as
+// plain final text without setting `isError`. Keep this fallback at the bridge
+// boundary so business logic never has to guess.
+const CLAWORLD_RELAY_RUNTIME_ERROR_PATTERNS = [
+  /^⚠️\s*Agent failed before reply:/i,
+  /^LLM request failed:/i,
+  /^LLM request timed out\./i,
+  /^LLM request unauthorized\./i,
+  /^The AI service is temporarily overloaded\./i,
+  /^The AI service returned an error\./i,
+  /^⚠️\s*API rate limit reached\./i,
+  /^⚠️\s*.+\s+returned a billing error\b/i,
+];
+
 const CLAWORLD_RELAY_OPERATIONAL_SUFFIX_PATTERNS = [
   /^Usage:\s+.+\s+in\s+\/\s+.+\s+out(?:\s+·\s+est\s+.+)?$/i,
 ];
@@ -201,18 +218,21 @@ function classifyRelayContinuationText(text) {
   if (!normalized) {
     return {
       text: '',
-      operational: Boolean(String(text || '').trim()),
+      operationalNotice: Boolean(String(text || '').trim()),
+      runtimeError: false,
     };
   }
   if (CLAWORLD_RELAY_OPERATIONAL_NOTICE_PATTERNS.some((pattern) => pattern.test(normalized))) {
     return {
       text: '',
-      operational: true,
+      operationalNotice: true,
+      runtimeError: false,
     };
   }
   return {
     text: normalized,
-    operational: false,
+    operationalNotice: false,
+    runtimeError: false,
   };
 }
 
@@ -220,6 +240,45 @@ function sanitizeRelayContinuationText(text) {
   return classifyRelayContinuationText(text).text;
 }
 
+function classifyRelayContinuationPayload(payload = {}) {
+  const rawText = String(payload?.text ?? payload?.body ?? '').trim();
+  const normalized = stripRelayOperationalSuffix(rawText);
+  const textClassification = classifyRelayContinuationText(rawText);
+  const runtimeError = payload?.isError === true
+    || CLAWORLD_RELAY_RUNTIME_ERROR_PATTERNS.some((pattern) => pattern.test(normalized));
+  if (runtimeError) {
+    return {
+      text: '',
+      previewText: normalized,
+      operationalNotice: false,
+      runtimeError: true,
+      nonRenderable: true,
+    };
+  }
+  return {
+    text: textClassification.text,
+    previewText: normalized,
+    operationalNotice: textClassification.operationalNotice,
+    runtimeError: false,
+    nonRenderable: textClassification.operationalNotice,
+  };
+}
+
+function resolveRelaySilentReason(runtimeOutputSummary = {}, continuation = {}) {
+  const counts = runtimeOutputSummary?.counts || {};
+  if (Number(counts.runtimeErrorFinal || 0) > 0) {
+    return 'runtime_failed_before_reply';
+  }
+  if (Number(counts.operationalNotice || 0) > 0 && Number(counts.nonRenderableFinal || 0) === Number(counts.final || 0)) {
+    return 'operational_notice_only';
+  }
+  const normalizedSource = normalizePluginOptionalText(continuation?.source);
+  if (normalizedSource && normalizedSource !== 'none') {
+    return normalizedSource;
+  }
+  return 'no_renderable_reply';
+}
+
 function previewRuntimeOutputText(text, maxLength = 120) {
   const normalized = String(text || '').replace(/\s+/g, ' ').trim();
   if (!normalized) return '';
@@ -1269,7 +1328,9 @@ function createDeliveryReplyDispatcher({
       reasoningEnd: 0,
       compactionStart: 0,
       compactionEnd: 0,
+      nonRenderableFinal: 0,
       operationalNotice: 0,
+      runtimeErrorFinal: 0,
     },
     previews: {
       final: [],
@@ -1278,6 +1339,7 @@ function createDeliveryReplyDispatcher({
       partial: [],
       reasoning: [],
       operationalNotice: [],
+      runtimeErrorFinal: [],
     },
     relayContinuationSource: 'none',
     relayContinuationPreview: null,
@@ -1288,14 +1350,21 @@ function createDeliveryReplyDispatcher({
     runtimeOutputSummary.counts[kind] += 1;
     const text = String(payload?.text ?? payload?.body ?? '').trim();
     if (kind === 'final') {
-      if (text) {
-        finalTexts.push(text);
-        appendRuntimeOutputPreview(runtimeOutputSummary.previews.final, text);
-        const classified = classifyRelayContinuationText(text);
-        if (classified.operational) {
-          runtimeOutputSummary.counts.operationalNotice += 1;
-          appendRuntimeOutputPreview(runtimeOutputSummary.previews.operationalNotice, text);
-        }
+      const classified = classifyRelayContinuationPayload(payload);
+      if (classified.text) {
+        finalTexts.push(classified.text);
+        appendRuntimeOutputPreview(runtimeOutputSummary.previews.final, classified.text);
+      }
+      if (classified.nonRenderable) {
+        runtimeOutputSummary.counts.nonRenderableFinal += 1;
+      }
+      if (classified.operationalNotice) {
+        runtimeOutputSummary.counts.operationalNotice += 1;
+        appendRuntimeOutputPreview(runtimeOutputSummary.previews.operationalNotice, classified.previewText || text);
+      }
+      if (classified.runtimeError) {
+        runtimeOutputSummary.counts.runtimeErrorFinal += 1;
+        appendRuntimeOutputPreview(runtimeOutputSummary.previews.runtimeErrorFinal, classified.previewText || text);
       }
       return;
     }
@@ -1411,21 +1480,35 @@ function createDeliveryReplyDispatcher({
   const markDispatchIdle = async () => {
     await dispatchApi.dispatcher.waitForIdle?.();
     if (!replied && !suppressed) {
-      const continuation = buildRelayContinuationText({
+      const allowPartialFallback = (
+        runtimeOutputSummary.counts.final > 0
+        && finalTexts.length === 0
+        && blockTexts.length === 0
+        && runtimeOutputSummary.counts.nonRenderableFinal === 0
+      );
+      const safeContinuation = buildRelayContinuationText({
         finalTexts,
         blockTexts,
         partialText: partialContinuationText,
-        allowPartialFallback:
-          runtimeOutputSummary.counts.final > 0 && finalTexts.length === 0 && blockTexts.length === 0,
+        allowPartialFallback,
       });
-      runtimeOutputSummary.relayContinuationSource = continuation.source;
-      runtimeOutputSummary.relayContinuationPreview = continuation.text
-        ? previewRuntimeOutputText(continuation.text)
+      runtimeOutputSummary.relayContinuationSource = safeContinuation.source;
+      runtimeOutputSummary.relayContinuationPreview = safeContinuation.text
+        ? previewRuntimeOutputText(safeContinuation.text)
         : null;
-      if (continuation.text) {
-        await flushReply(continuation.text);
+      if (safeContinuation.text) {
+        await flushReply(safeContinuation.text);
       } else {
-        await flushKeptSilent(continuation.source);
+        const silentReason = resolveRelaySilentReason(runtimeOutputSummary, safeContinuation);
+        if (runtimeOutputSummary.counts.runtimeErrorFinal > 0) {
+          logger.warn?.(`[claworld:${runtimeAccountId}] runtime produced non-renderable error finals; returning kept_silent`, {
+            deliveryId,
+            sessionKey,
+            localAgentId,
+            runtimeOutputSummary,
+          });
+        }
+        await flushKeptSilent(silentReason);
       }
     }
     await dispatchApi.markDispatchIdle?.();
@@ -1470,13 +1553,14 @@ function createDeliveryReplyDispatcher({
         final: [...runtimeOutputSummary.previews.final],
         block: [...runtimeOutputSummary.previews.block],
         tool: [...runtimeOutputSummary.previews.tool],
-        partial: [...runtimeOutputSummary.previews.partial],
-        reasoning: [...runtimeOutputSummary.previews.reasoning],
-        operationalNotice: [...runtimeOutputSummary.previews.operationalNotice],
-      },
-      relayContinuationSource: runtimeOutputSummary.relayContinuationSource,
-      relayContinuationPreview: runtimeOutputSummary.relayContinuationPreview,
-      replyTransport,
+      partial: [...runtimeOutputSummary.previews.partial],
+      reasoning: [...runtimeOutputSummary.previews.reasoning],
+      operationalNotice: [...runtimeOutputSummary.previews.operationalNotice],
+      runtimeErrorFinal: [...runtimeOutputSummary.previews.runtimeErrorFinal],
+    },
+    relayContinuationSource: runtimeOutputSummary.relayContinuationSource,
+    relayContinuationPreview: runtimeOutputSummary.relayContinuationPreview,
+    replyTransport,
       replyFallbackUsed,
       keptSilentTransport,
       keptSilentFallbackUsed,
@@ -1749,8 +1833,8 @@ async function maybeBridgeRuntimeDelivery({
     && metadata.allowReply !== false
     && replied !== true
     && runtimeOutputSummary.counts.final > 0
-    && runtimeOutputSummary.counts.operationalNotice > 0
-    && runtimeOutputSummary.counts.final === runtimeOutputSummary.counts.operationalNotice
+    && runtimeOutputSummary.counts.nonRenderableFinal > 0
+    && runtimeOutputSummary.counts.final === runtimeOutputSummary.counts.nonRenderableFinal
     && runtimeOutputSummary.counts.block === 0
     && runtimeOutputSummary.counts.tool === 0
     && runtimeOutputSummary.counts.partial === 0
@@ -2369,7 +2453,7 @@ export function createClaworldChannelPlugin({
     return {
       ok: true,
       pluginId: 'claworld',
-      version: '0.3.0',
+      version: CLAWORLD_PLUGIN_VERSION,
       defaultAccountId: null,
       accounts: accountSnapshots,
       relayClients: Object.fromEntries(
@@ -2518,7 +2602,7 @@ async function generateRuntimeProfileCard(context = {}) {
       docsPath: '/channels/claworld',
       docsLabel: 'claworld',
       blurb: 'Claworld relay channel backed by the Claworld backend.',
-      version: '0.3.0',
+      version: CLAWORLD_PLUGIN_VERSION,
       forceAccountBinding: true,
     },
     onboarding: claworldOnboardingAdapter,

package/src/openclaw/runtime/tool-contracts.js

@@ -1,3 +1,5 @@
+import { normalizeAcceptedChatKickoffRecord } from '../../lib/relay/kickoff-progress.js';
+
 function normalizeText(value, fallback = null) {
   if (value == null) return fallback;
   const normalized = String(value).trim();
@@ -437,15 +439,19 @@ function normalizeConversationScopeDetails(input = {}) {
 }
 
 function projectChatRequestKickoff(kickoff = {}) {
-  if (!kickoff || typeof kickoff !== 'object') return null;
+  const normalizedKickoff = normalizeAcceptedChatKickoffRecord(kickoff, { fallbackStatus: 'skipped' });
+  if (!normalizedKickoff) return null;
   return {
-    status: normalizeText(kickoff.status, 'skipped'),
-    deliveredAt: normalizeText(kickoff.deliveredAt, null),
-    senderKickoffDeliveredAt: normalizeText(kickoff.senderKickoffDeliveredAt, normalizeText(kickoff.deliveredAt, null)),
-    openerAcceptedAt: normalizeText(kickoff.openerAcceptedAt, null),
-    openerDeliveredAt: normalizeText(kickoff.openerDeliveredAt, null),
-    liveChatEstablishedAt: normalizeText(kickoff.liveChatEstablishedAt, null),
-    reason: normalizeText(kickoff.reason, null),
+    status: normalizeText(normalizedKickoff.status, 'skipped'),
+    deliveredAt: normalizeText(normalizedKickoff.deliveredAt, null),
+    senderKickoffDeliveredAt: normalizeText(
+      normalizedKickoff.senderKickoffDeliveredAt,
+      normalizeText(normalizedKickoff.deliveredAt, null),
+    ),
+    openerAcceptedAt: normalizeText(normalizedKickoff.openerAcceptedAt, null),
+    openerDeliveredAt: normalizeText(normalizedKickoff.openerDeliveredAt, null),
+    liveChatEstablishedAt: normalizeText(normalizedKickoff.liveChatEstablishedAt, null),
+    reason: normalizeText(normalizedKickoff.reason, null),
   };
 }