@xfxstudio/claworld 2026.5.10-testing.1 → 2026.5.14-testing.1

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

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import path from 'node:path';
 
 import {
   applyRuntimeIdentity,
@@ -32,6 +33,15 @@ import { createInboundSessionRouter } from '../runtime/inbound-session-router.js
 import { createOutboundSessionBridge } from '../runtime/outbound-session-bridge.js';
 import { createCanonicalResultBuilder } from '../runtime/canonical-result-builder.js';
 import { createDemoSessionBootstrap } from '../runtime/demo-session-bootstrap.js';
+import {
+  CLAWORLD_PUBLIC_TOOL_NAMES,
+  CLAWORLD_RETIRED_PUBLIC_TOOL_NAMES,
+  CLAWORLD_TOOL_CONTRACT_VERSION,
+} from '../runtime/tool-inventory.js';
+import {
+  appendClaworldJournalEvent,
+  buildClaworldRuntimeMaintenanceEvent,
+} from '../runtime/working-memory.js';
 import {
   broadcastModeratedWorld,
   createModeratedWorld,
@@ -62,6 +72,7 @@ import {
   resolveWorldSelectionFlow,
 } from '../runtime/product-shell-helper.js';
 import { extractBackendErrorContext } from '../runtime/backend-error-context.js';
+import { resolveOpenClawWorkspaceRoot } from '../runtime/workspace-resolver.js';
 import { getClaworldRuntime } from './runtime.js';
 import {
   CLAWORLD_PLUGIN_CURRENT_VERSION,
@@ -582,19 +593,17 @@ async function deliverRelayMessage({ runtimeConfig, to, text, fetchImpl, logger,
 
   if (!result.ok) {
     logger.error?.('[claworld:outbound] message delivery failed', { status: result.status, body: result.body });
-    throw createRuntimeBoundaryError({
+    createRelayRouteError({
+      result,
+      runtimeConfig,
       code: 'relay_message_delivery_failed',
-      category: 'transport',
-      status: result.status >= 500 ? 502 : result.status,
-      message: `claworld outbound failed: ${result.status}`,
       publicMessage: 'claworld outbound message delivery failed',
-      recoverable: true,
+      message: `claworld outbound failed: ${result.status}`,
       context: {
-        accountId: runtimeConfig.accountId || null,
         fromAgentId,
         targetAgentId,
-        status: result.status,
       },
+      passThroughBackendConflict: true,
     });
   }
 
@@ -630,13 +639,23 @@ function createRelayRouteError({
   publicMessage,
   message,
   context = {},
+  passThroughBackendConflict = false,
 }) {
+  const backendCode = resolveNormalizedText(result?.body?.error, null);
+  const backendMessage = resolveNormalizedText(result?.body?.message, null);
+  const shouldPassThroughConflict = passThroughBackendConflict === true
+    && Number(result?.status) === 409
+    && backendCode;
   throw createRuntimeBoundaryError({
-    code,
-    category: 'transport',
+    code: shouldPassThroughConflict ? backendCode : code,
+    category: shouldPassThroughConflict ? 'conflict' : 'transport',
     status: result?.status >= 500 ? 502 : result?.status || 502,
-    message: message || publicMessage,
-    publicMessage,
+    message: shouldPassThroughConflict
+      ? (backendMessage || message || publicMessage)
+      : (message || publicMessage),
+    publicMessage: shouldPassThroughConflict
+      ? (backendMessage || publicMessage)
+      : publicMessage,
     recoverable: true,
     context: {
       accountId: runtimeConfig.accountId || null,
@@ -727,6 +746,7 @@ async function createChatRequest({
         displayName: normalizedDisplayName,
         agentCode: normalizedAgentCode,
       },
+      passThroughBackendConflict: true,
     });
   }
   return result.body || {};
@@ -809,6 +829,7 @@ async function acceptChatRequest({
       code: 'chat_request_accept_failed',
       publicMessage: 'failed to accept chat request',
       context: { actorAgentId, chatRequestId },
+      passThroughBackendConflict: true,
     });
   }
   return normalizeChatInboxPayloadSessionKeys(result.body || {}, { localAgentId });
@@ -837,6 +858,7 @@ async function rejectChatRequest({
       code: 'chat_request_reject_failed',
       publicMessage: 'failed to reject chat request',
       context: { actorAgentId, chatRequestId },
+      passThroughBackendConflict: true,
     });
   }
   return result.body || {};
@@ -1841,6 +1863,297 @@ function buildDeliveryInboundEnvelope({
   };
 }
 
+function normalizeSessionStoreKey(value) {
+  return resolveNormalizedText(value, '').toLowerCase();
+}
+
+function resolveSessionStoreEntry(store = null, sessionKey = null) {
+  if (!store || typeof store !== 'object' || Array.isArray(store)) return null;
+  const normalizedSessionKey = resolveNormalizedText(sessionKey, null);
+  if (!normalizedSessionKey) return null;
+  if (store[normalizedSessionKey] && typeof store[normalizedSessionKey] === 'object') {
+    return store[normalizedSessionKey];
+  }
+  const lowerSessionKey = normalizeSessionStoreKey(normalizedSessionKey);
+  if (store[lowerSessionKey] && typeof store[lowerSessionKey] === 'object') {
+    return store[lowerSessionKey];
+  }
+  const match = Object.entries(store).find(([key, value]) => (
+    normalizeSessionStoreKey(key) === lowerSessionKey
+    && value
+    && typeof value === 'object'
+    && !Array.isArray(value)
+  ));
+  return match ? match[1] : null;
+}
+
+function readRuntimeSessionStoreEntry({ runtime = null, sessionStorePath = null, sessionKey = null } = {}) {
+  if (!runtime?.agent?.session?.loadSessionStore || !sessionStorePath || !sessionKey) return null;
+  try {
+    return resolveSessionStoreEntry(
+      runtime.agent.session.loadSessionStore(sessionStorePath),
+      sessionKey,
+    );
+  } catch {
+    return null;
+  }
+}
+
+function resolveSessionFilePathFromRuntime({
+  runtime = null,
+  sessionId = null,
+  record = {},
+  sessionStorePath = null,
+  localAgentId = null,
+} = {}) {
+  const normalizedSessionId = resolveNormalizedText(sessionId, null);
+  if (!normalizedSessionId) return null;
+
+  const sessionsDir = sessionStorePath
+    ? path.dirname(path.resolve(sessionStorePath))
+    : null;
+  if (typeof runtime?.agent?.session?.resolveSessionFilePath === 'function') {
+    try {
+      const resolved = runtime.agent.session.resolveSessionFilePath(
+        normalizedSessionId,
+        record,
+        {
+          ...(sessionsDir ? { sessionsDir } : {}),
+          ...(localAgentId ? { agentId: localAgentId } : {}),
+        },
+      );
+      const normalized = resolveNormalizedText(resolved, null);
+      if (normalized) return normalized;
+    } catch {
+      // Fall through to the local derivation below.
+    }
+  }
+
+  const candidate = resolveNormalizedText(record?.sessionFile, null);
+  if (candidate) {
+    if (path.isAbsolute(candidate) || !sessionsDir) return candidate;
+    return path.resolve(sessionsDir, candidate);
+  }
+
+  if (sessionsDir) {
+    return path.join(sessionsDir, `${normalizedSessionId}.jsonl`);
+  }
+  return null;
+}
+
+function resolveSessionRecordArtifacts(record = null, fallbackStorePath = null, options = {}) {
+  const normalizedRecord = record && typeof record === 'object' && !Array.isArray(record) ? record : {};
+  const nestedSession = normalizedRecord.session && typeof normalizedRecord.session === 'object' && !Array.isArray(normalizedRecord.session)
+    ? normalizedRecord.session
+    : {};
+  const sessionId = resolveNormalizedText(
+    normalizedRecord.sessionId,
+    resolveNormalizedText(nestedSession.sessionId, resolveNormalizedText(normalizedRecord.id, null)),
+  );
+  const sessionStorePath = resolveNormalizedText(
+    normalizedRecord.storePath,
+    resolveNormalizedText(normalizedRecord.sessionStorePath, fallbackStorePath),
+  );
+  const directSessionFile = resolveNormalizedText(
+    normalizedRecord.sessionFile,
+    resolveNormalizedText(
+      normalizedRecord.sessionPath,
+      resolveNormalizedText(
+        normalizedRecord.filePath,
+        resolveNormalizedText(normalizedRecord.path, resolveNormalizedText(nestedSession.filePath, null)),
+      ),
+    ),
+  );
+  const sessionFile = directSessionFile || resolveSessionFilePathFromRuntime({
+    runtime: options.runtime,
+    sessionId,
+    record: normalizedRecord,
+    sessionStorePath,
+    localAgentId: options.localAgentId,
+  });
+  const transcriptPath = resolveNormalizedText(
+    normalizedRecord.transcriptPath,
+    resolveNormalizedText(nestedSession.transcriptPath, sessionFile),
+  );
+  return {
+    sessionId,
+    sessionFile,
+    sessionStorePath,
+    transcriptPath,
+  };
+}
+
+async function recordRuntimeInboundSessionArtifacts({
+  runtime = null,
+  currentCfg = {},
+  localAgentId = null,
+  sessionKey = null,
+  ctx = {},
+  logger = console,
+  runtimeAccountId = null,
+  logLabel = 'inbound',
+  logContext = {},
+} = {}) {
+  let sessionStorePath = null;
+  let sessionRecord = null;
+  const sessionApi = runtime?.channel?.session || {};
+  const localSessionKey = resolveNormalizedText(ctx?.SessionKey, sessionKey);
+
+  if (sessionApi.resolveStorePath && localAgentId) {
+    sessionStorePath = sessionApi.resolveStorePath(currentCfg.session?.store, {
+      agentId: localAgentId,
+    });
+    const onRecordError = (error) => {
+      logger.error?.(`[claworld:${runtimeAccountId}] failed to record ${logLabel} inbound session`, {
+        ...logContext,
+        sessionKey,
+        localSessionKey,
+        localAgentId,
+        error: error?.message || String(error),
+      });
+    };
+    try {
+      if (typeof sessionApi.recordSessionMetaFromInbound === 'function') {
+        sessionRecord = await sessionApi.recordSessionMetaFromInbound({
+          storePath: sessionStorePath,
+          sessionKey: localSessionKey,
+          ctx,
+        });
+      } else if (typeof sessionApi.recordInboundSession === 'function') {
+        sessionRecord = await sessionApi.recordInboundSession({
+          storePath: sessionStorePath,
+          sessionKey: localSessionKey,
+          ctx,
+          onRecordError,
+        });
+      }
+    } catch (error) {
+      onRecordError(error);
+    }
+    if (!sessionRecord) {
+      sessionRecord = readRuntimeSessionStoreEntry({
+        runtime,
+        sessionStorePath,
+        sessionKey: localSessionKey,
+      });
+    }
+  }
+
+  return {
+    sessionStorePath,
+    sessionRecord,
+    sessionArtifacts: resolveSessionRecordArtifacts(sessionRecord, sessionStorePath, {
+      runtime,
+      localAgentId,
+    }),
+  };
+}
+
+function buildInboundRuntimeMaintenanceEvent({
+  delivery = {},
+  metadata = {},
+  payload = {},
+  messageId = null,
+  eventType = 'delivery',
+  sessionKind = null,
+  localSessionKey = null,
+  localAgentId = null,
+  sessionArtifacts = {},
+  workspaceRoot = null,
+} = {}) {
+  const normalizedEventType = resolveNormalizedText(eventType, 'delivery');
+  const isRelayDelivery = normalizedEventType === 'delivery';
+  const sessionKey = resolveNormalizedText(delivery.sessionKey, null);
+  const requestId = resolveNormalizedText(
+    metadata.kickoffRequestId,
+    resolveNormalizedText(metadata.requestId, resolveNormalizedText(metadata.chatRequestId, null)),
+  );
+  const worldId = resolveNormalizedText(
+    metadata.worldId,
+    resolveNormalizedText(delivery.worldId, resolveNormalizedText(payload.worldId, null)),
+  );
+  const conversationKey = resolveNormalizedText(
+    metadata.conversationKey,
+    resolveNormalizedText(delivery.conversationKey, resolveNormalizedText(payload.conversationKey, null)),
+  );
+  const fromAgentId = resolveNormalizedText(metadata.fromAgentId, null);
+  const targetAgentId = resolveNormalizedText(
+    delivery.targetAgentId,
+    resolveNormalizedText(payload.targetAgentId, resolveNormalizedText(metadata.targetAgentId, null)),
+  );
+  const notificationId = resolveNormalizedText(
+    metadata.notificationId,
+    resolveNormalizedText(payload.notificationId, null),
+  );
+  const inboxItemId = resolveNormalizedText(
+    metadata.inboxItemId,
+    resolveNormalizedText(payload.inboxItemId, null),
+  );
+  const scope = sessionKind === 'management' ? 'management' : 'conversation';
+  const summary = [
+    isRelayDelivery
+      ? 'Inbound Claworld delivery joined local session'
+      : 'Inbound Claworld runtime input joined local session',
+    requestId ? `for request ${requestId}` : null,
+    fromAgentId ? `from ${fromAgentId}` : null,
+  ].filter(Boolean).join(' ');
+  return buildClaworldRuntimeMaintenanceEvent({
+    id: messageId ? `runtime:${normalizedEventType}:${messageId}` : null,
+    timestamp: delivery.createdAt || metadata.createdAt || payload.createdAt || null,
+    kind: isRelayDelivery
+      ? (metadata.deliveryType ? `delivery.${metadata.deliveryType}` : 'delivery')
+      : 'runtime_event',
+    eventType: normalizedEventType,
+    scope,
+    summary,
+    excerpt: isRelayDelivery
+      ? (
+        payload.contextText
+          ? 'Inbound delivery included contextText; raw dialogue is kept in the OpenClaw session transcript.'
+          : 'Inbound delivery routed into an OpenClaw session after backend session resolution.'
+      )
+      : 'Inbound runtime input routed into an OpenClaw session after backend session resolution.',
+    refs: {
+      deliveryId: isRelayDelivery ? messageId : null,
+      eventId: messageId,
+      requestId,
+      chatRequestId: requestId,
+      worldId,
+      conversationKey,
+      fromAgentId,
+      targetAgentId,
+      notificationId,
+      inboxItemId,
+      sessionKey: localSessionKey || sessionKey,
+      relaySessionKey: sessionKey,
+    },
+    relations: {
+      deliveryId: isRelayDelivery ? messageId : null,
+      eventId: messageId,
+      requestId,
+      chatRequestId: requestId,
+      worldId,
+      conversationKey,
+      fromAgentId,
+      targetAgentId,
+      notificationId,
+      inboxItemId,
+      localAgentId,
+      localSessionKey,
+      relaySessionKey: sessionKey,
+      sessionKey: localSessionKey || sessionKey,
+      sessionId: sessionArtifacts.sessionId,
+      sessionFile: sessionArtifacts.sessionFile,
+      sessionStorePath: sessionArtifacts.sessionStorePath,
+      transcriptPath: sessionArtifacts.transcriptPath,
+    },
+    artifacts: {
+      workspaceRoot,
+      ...sessionArtifacts,
+    },
+  });
+}
+
 function createDeliveryReplyDispatcher({
   runtime,
   currentCfg,
@@ -2232,18 +2545,14 @@ async function maybeBridgeRuntimeInboundEvent({
   const contextText = resolveNormalizedText(payload.contextText, null);
   const incomingText = resolveNormalizedText(
     payload.commandText,
-    contextText ? null : resolveNormalizedText(payload.text, resolveNormalizedText(payload.body, null)),
+    contextText
+      ? null
+      : resolveNormalizedText(payload.text, resolveNormalizedText(payload.body, null)),
   );
   const commandText = resolveNormalizedText(payload.commandText, incomingText);
   const fromAgentId = resolveNormalizedText(metadata.fromAgentId, null);
-  const routeSessionKind = resolveNormalizedText(
-    event?.route?.sessionKind,
-    resolveNormalizedText(delivery.sessionKind, resolveNormalizedText(payload.sessionKind, null)),
-  );
   const isRelayDelivery = eventType === 'delivery';
   const allowReply = metadata.allowReply === true || (isRelayDelivery && metadata.allowReply !== false);
-  const remoteIdentity = fromAgentId
-    || resolveNormalizedText(metadata.source, routeSessionKind === 'management' ? 'claworld-management' : 'unknown-peer');
 
   if (
     !runtime?.channel?.reply?.finalizeInboundContext
@@ -2290,6 +2599,12 @@ async function maybeBridgeRuntimeInboundEvent({
     sessionTarget: runtimeConfig.routing?.sessionTarget,
     fallbackTarget: runtimeConfig.routing?.fallbackTarget,
   }) || null;
+  const routeSessionKind = resolveNormalizedText(
+    event?.route?.sessionKind,
+    resolveNormalizedText(routed?.sessionKind, null),
+  );
+  const remoteIdentity = fromAgentId
+    || resolveNormalizedText(metadata.source, routeSessionKind === 'management' ? 'claworld-management' : 'unknown-peer');
   const worldId = resolveDeliveryWorldId(delivery);
   const commandAuthorized = isRelayDelivery && shouldAuthorizeBridgedCommand({
     runtimeConfig,
@@ -2331,6 +2646,9 @@ async function maybeBridgeRuntimeInboundEvent({
     OriginatingFrom: remoteIdentity,
     OriginatingTo: remoteIdentity,
     ChatType: isManagementSession ? 'management' : 'direct',
+    SessionType: isManagementSession ? 'management' : 'direct',
+    sessionType: isManagementSession ? 'management' : 'direct',
+    sessionKind: isManagementSession ? 'management' : 'conversation',
     SenderName: senderName,
     SenderId: remoteIdentity,
     MessageId: deliveryId,
@@ -2346,26 +2664,21 @@ async function maybeBridgeRuntimeInboundEvent({
     UntrustedContext,
   });
 
-  if (runtime?.channel?.session?.recordInboundSession && runtime?.channel?.session?.resolveStorePath && localAgentId) {
-    const storePath = runtime.channel.session.resolveStorePath(currentCfg.session?.store, {
-      agentId: localAgentId,
-    });
-    await runtime.channel.session.recordInboundSession({
-      storePath,
-      sessionKey: inboundCtx.SessionKey || sessionKey,
-      ctx: inboundCtx,
-      onRecordError: (error) => {
-        logger.error?.(`[claworld:${runtimeAccountId}] failed to record inbound session`, {
-          eventType,
-          deliveryId,
-          sessionKey,
-          localSessionKey,
-          localAgentId,
-          error: error?.message || String(error),
-        });
-      },
-    });
-  }
+  const {
+    sessionArtifacts,
+  } = await recordRuntimeInboundSessionArtifacts({
+    runtime,
+    currentCfg,
+    localAgentId,
+    sessionKey,
+    ctx: inboundCtx,
+    logger,
+    runtimeAccountId,
+    logContext: {
+      eventType,
+      deliveryId,
+    },
+  });
 
   logger.info?.(`[claworld:${runtimeAccountId}] ${isRelayDelivery ? 'routing delivery into runtime session' : 'routing inbound event into runtime session'}`, {
     eventType,
@@ -2467,16 +2780,54 @@ async function maybeBridgeRuntimeInboundEvent({
     }));
   }
 
+  let journalResult = null;
+  const workspaceRoot = resolveOpenClawWorkspaceRoot({
+    sources: [
+      { agentId: localAgentId, localAgentId },
+      currentCfg,
+      runtimeConfig,
+    ],
+    config: currentCfg,
+    agentId: localAgentId,
+  });
+  if (workspaceRoot) {
+    try {
+      const maintenanceEvent = buildInboundRuntimeMaintenanceEvent({
+        delivery,
+        metadata,
+        payload,
+        messageId: deliveryId,
+        eventType,
+        sessionKind: routeSessionKind,
+        localSessionKey,
+        localAgentId,
+        sessionArtifacts,
+        workspaceRoot,
+      });
+      journalResult = await appendClaworldJournalEvent(workspaceRoot, maintenanceEvent);
+    } catch (error) {
+      logger.warn?.(`[claworld:${runtimeAccountId}] inbound journal append failed`, {
+        eventType,
+        deliveryId,
+        sessionKey,
+        error: error?.message || String(error),
+      });
+    }
+  }
+
   logger.info?.(`[claworld:${runtimeAccountId}] ${isRelayDelivery ? 'delivery bridge completed' : 'inbound bridge completed'}`, {
     eventType,
     deliveryId,
     sessionKey,
     localSessionKey,
+    sessionId: sessionArtifacts.sessionId || null,
+    sessionFile: sessionArtifacts.sessionFile || null,
     queuedFinal: Boolean(dispatchResult?.queuedFinal),
     replied,
     keptSilent,
     routeStatus: routed?.status || null,
     runtimeOutputSummary,
+    journal: journalResult?.ok === true,
   });
 
   return {
@@ -3063,6 +3414,9 @@ export function createClaworldChannelPlugin({
       ok: true,
       pluginId: 'claworld',
       version: CLAWORLD_PLUGIN_CURRENT_VERSION,
+      toolContractVersion: CLAWORLD_TOOL_CONTRACT_VERSION,
+      publicToolNames: [...CLAWORLD_PUBLIC_TOOL_NAMES],
+      retiredPublicToolNames: [...CLAWORLD_RETIRED_PUBLIC_TOOL_NAMES],
       defaultAccountId: null,
       accounts: accountSnapshots,
       relayClients: Object.fromEntries(