@xfxstudio/claworld 2026.4.22-testing.5 → 2026.4.22-testing.7

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

@@ -683,6 +683,7 @@ export class ClaworldRelayClient extends EventEmitter {
       const cleanup = () => {
         if (timeout) clearTimeout(timeout);
         this.off('reply.accepted', onReplyAccepted);
+        this.off('command.accepted', onCommandAccepted);
         this.off('disconnect', onDisconnect);
         this.off('close', onDisconnect);
       };
@@ -707,6 +708,20 @@ export class ClaworldRelayClient extends EventEmitter {
         settleResolve(message);
       };
 
+      const onCommandAccepted = (message = {}) => {
+        const command = message?.data?.command && typeof message.data.command === 'object'
+          ? message.data.command
+          : {};
+        if (normalizeOptionalText(command.name) !== 'delivery.reply.requested') return;
+        const commandDeliveryId = [
+          command.deliveryId,
+          command.aggregateId,
+          command.partitionKey,
+        ].map((value) => normalizeOptionalText(value)).find(Boolean) || null;
+        if (commandDeliveryId !== normalizedDeliveryId) return;
+        settleResolve(message);
+      };
+
       const onDisconnect = (info = {}) => {
         settleReject(createRuntimeBoundaryError({
           code: 'relay_reply_ack_disconnected',
@@ -725,6 +740,7 @@ export class ClaworldRelayClient extends EventEmitter {
       };
 
       this.on('reply.accepted', onReplyAccepted);
+      this.on('command.accepted', onCommandAccepted);
       this.on('disconnect', onDisconnect);
       this.on('close', onDisconnect);
 

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

@@ -1,3 +1,9 @@
+import {
+  buildAgentWorkingMemoryArtifactIndex,
+  buildManagementSessionKey,
+  createManagementWorkingMemoryBootstrapContext,
+} from './session-routing.js';
+
 export function createDemoSessionBootstrap() {
   return {
     defaults: {
@@ -28,5 +34,47 @@ export function createDemoSessionBootstrap() {
         status: 'planned',
       };
     },
+    createManagementBootstrapPlan({
+      agentId,
+      trigger = 'management_wake',
+      workingMemoryRoot = '.claworld',
+      now = null,
+      event = {},
+    } = {}) {
+      const context = createManagementWorkingMemoryBootstrapContext({
+        agentId,
+        trigger,
+        workingMemoryRoot,
+        now,
+        event,
+      });
+      return {
+        status: context.sessionKey ? 'planned' : 'invalid',
+        sessionKind: 'management',
+        sessionKey: context.sessionKey,
+        agentId: context.agentId,
+        trigger: context.trigger,
+        artifactIndex: context.artifactIndex,
+        steps: context.bootstrapChecklist,
+      };
+    },
+    createAgentWorkingMemoryPlan({
+      agentId,
+      workingMemoryRoot = '.claworld',
+      now = null,
+    } = {}) {
+      const artifactIndex = buildAgentWorkingMemoryArtifactIndex({
+        agentId,
+        root: workingMemoryRoot,
+        now,
+      });
+      return {
+        status: 'planned',
+        agentId: artifactIndex.agentId,
+        sessionKey: buildManagementSessionKey(artifactIndex.agentId),
+        artifactIndex,
+        requiredFiles: artifactIndex.requiredFiles,
+      };
+    },
   };
 }

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

@@ -1,4 +1,5 @@
 import { OPENCLAW_RUNTIME_PATH, createRuntimePathTrace } from './runtime-path.js';
+import { resolveRuntimeSessionTarget } from './session-routing.js';
 
 function normalizeText(value, fallback = null) {
   if (value == null) return fallback;
@@ -17,15 +18,21 @@ export function createInboundSessionRouter() {
     routeInboundEvent(event = {}, options = {}) {
       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);
+      const target = resolveRuntimeSessionTarget(event, options);
+      const sessionKey = target.sessionKey;
       return {
-        action: 'route_delivery',
-        target: normalizeText(options.sessionTarget, 'mainagent'),
+        action: target.sessionKind === 'management' ? 'route_management_input' : 'route_delivery',
+        target: target.target,
         fallbackTarget: normalizeText(options.fallbackTarget, 'mainagent'),
+        sessionKind: target.sessionKind,
         eventType,
         deliveryId,
         sessionKey,
+        managementSessionKey: target.managementSessionKey,
+        conversationSessionKey: target.conversationSessionKey,
+        targetAgentId: target.targetAgentId,
+        conversationKey: target.conversationKey,
         payload,
         metadata: event.metadata && typeof event.metadata === 'object' && !Array.isArray(event.metadata)
           ? { ...event.metadata }
@@ -35,7 +42,16 @@ export function createInboundSessionRouter() {
           eventId: deliveryId,
           direction: 'inbound',
         }),
-        status: eventType === 'delivery' && deliveryId && sessionKey && normalizeText(payload.text, null)
+        status: (
+          target.sessionKind === 'management'
+          && sessionKey
+          && eventType
+        ) || (
+          eventType === 'delivery'
+          && deliveryId
+          && sessionKey
+          && normalizeText(payload.text, null)
+        )
           ? 'resolved'
           : 'invalid',
       };

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

@@ -4,6 +4,16 @@ function normalizeText(value, fallback = null) {
   return normalized || fallback;
 }
 
+function clonePayload(value = null) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  return JSON.parse(JSON.stringify(value));
+}
+
+function buildManagementSessionKey(agentId = null) {
+  const normalizedAgentId = normalizeText(agentId, null);
+  return normalizedAgentId ? `management:${normalizedAgentId}` : null;
+}
+
 export function createOutboundSessionBridge() {
   return {
     createReplyEnvelope({
@@ -25,5 +35,55 @@ export function createOutboundSessionBridge() {
         },
       };
     },
+    createLongRunningIntentHandoffEnvelope({
+      agentId,
+      intentId = null,
+      summary,
+      allowedActions = [],
+      reportPolicy = 'material_updates',
+      sourceSessionKey = null,
+      payload = {},
+    } = {}) {
+      const sessionKey = buildManagementSessionKey(agentId);
+      return {
+        eventType: 'management_wake',
+        sessionKind: 'management',
+        sessionKey,
+        payload: {
+          eventType: 'management_wake',
+          reason: 'external_main_long_running_intent_handoff',
+          intentId: normalizeText(intentId, null),
+          summary: normalizeText(summary, ''),
+          allowedActions: Array.isArray(allowedActions)
+            ? allowedActions.map((action) => normalizeText(action, null)).filter(Boolean)
+            : [],
+          reportPolicy: normalizeText(reportPolicy, 'material_updates'),
+          sourceSessionKey: normalizeText(sourceSessionKey, null),
+          targetAgentId: normalizeText(agentId, null),
+          ...clonePayload(payload),
+        },
+      };
+    },
+    createManagementReportEnvelope({
+      agentId,
+      reportId = null,
+      reportText,
+      targetSessionKey = null,
+      payload = {},
+    } = {}) {
+      return {
+        eventType: 'management_report',
+        sessionKind: 'external_main',
+        sessionKey: normalizeText(targetSessionKey, null),
+        payload: {
+          eventType: 'management_report',
+          reportId: normalizeText(reportId, null),
+          text: normalizeText(reportText, ''),
+          sourceSessionKey: buildManagementSessionKey(agentId),
+          sourceAgentId: normalizeText(agentId, null),
+          ...clonePayload(payload),
+        },
+      };
+    },
   };
 }

package/src/openclaw/runtime/product-shell-helper.js

@@ -146,6 +146,7 @@ function normalizeWorldDetail(payload = {}) {
       ownerAgentId: normalizeText(payload.ownerAgentId, null),
       worldRole: normalizeWorldRole(payload.worldRole, null),
       enabled: typeof payload.enabled === 'boolean' ? payload.enabled : null,
+      broadcast: normalizeBroadcastConfig(payload.broadcast),
       requiredFieldCount: normalizeInteger(payload.requiredFieldCount, requiredFields.length) || requiredFields.length,
       optionalFieldCount: normalizeInteger(payload.optionalFieldCount, optionalFields.length) || optionalFields.length,
       requiredFields,
@@ -187,6 +188,7 @@ function normalizeWorldDetail(payload = {}) {
     worldRole: normalizeWorldRole(payload.worldRole, null),
     enabled: typeof management.enabled === 'boolean' ? management.enabled : null,
     statusLabel: normalizeText(management.status, null),
+    broadcast: normalizeBroadcastConfig(management.broadcast || payload.broadcast || world.broadcast),
     requiredFieldCount: 1,
     optionalFieldCount: 0,
     requiredFields,
@@ -253,6 +255,16 @@ function normalizeSearchAction(action = null) {
   };
 }
 
+function normalizeBroadcastConfig(broadcast = null) {
+  if (!broadcast || typeof broadcast !== 'object' || Array.isArray(broadcast)) return null;
+  return {
+    enabled: typeof broadcast.enabled === 'boolean' ? broadcast.enabled : null,
+    audience: normalizeText(broadcast.audience, null),
+    replyPolicy: normalizeText(broadcast.replyPolicy, null),
+    excludeSelf: typeof broadcast.excludeSelf === 'boolean' ? broadcast.excludeSelf : null,
+  };
+}
+
 function normalizeCompatibilitySignal(signal = {}, index = 0) {
   return {
     signalId: normalizeText(signal.signalId, `signal_${index + 1}`),
@@ -348,18 +360,16 @@ function normalizeCandidateFeedResponse(payload = {}, { worldId = null, agentId
   };
 }
 
+
+function normalizeActionPayload(value = null) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+
 export function normalizeWorldJoinResponse(payload = {}, { worldId = null, agentId = null } = {}) {
   const membership = payload.membership && typeof payload.membership === 'object' ? payload.membership : null;
   const normalizedWorldId = normalizeText(payload.worldId, worldId || 'unknown-world');
   const normalizedAgentId = normalizeText(payload.agentId || membership?.agentId, agentId || null);
   const membershipStatus = normalizeText(payload.membershipStatus || membership?.status, 'unknown');
-  const candidateFeed = payload.candidateFeed && typeof payload.candidateFeed === 'object'
-    ? normalizeCandidateFeedResponse(payload.candidateFeed, {
-      worldId: normalizedWorldId,
-      agentId: normalizedAgentId,
-    })
-    : null;
-
   return {
     status: normalizeText(payload.status, membershipStatus === 'active' ? 'joined' : 'accepted'),
     worldId: normalizedWorldId,
@@ -373,15 +383,15 @@ export function normalizeWorldJoinResponse(payload = {}, { worldId = null, agent
     membership,
     nextAction: normalizeText(
       payload.nextAction,
-      membershipStatus === 'active' ? 'review_candidate_feed' : null,
+      membershipStatus === 'active' ? 'search_world_members_or_view_activity' : null,
     ),
     nextStageSummary: payload.nextStageSummary && typeof payload.nextStageSummary === 'object'
       ? payload.nextStageSummary
       : {},
-    candidateFeed,
-    candidateDelivery: payload.candidateDelivery && typeof payload.candidateDelivery === 'object'
-      ? payload.candidateDelivery
-      : null,
+    memberSearchAction: normalizeActionPayload(payload.memberSearchAction),
+    worldActivityAction: normalizeActionPayload(payload.worldActivityAction),
+    subscribeWorldAction: normalizeActionPayload(payload.subscribeWorldAction),
+    requestChatAction: normalizeActionPayload(payload.requestChatAction),
     orchestration: payload.orchestration && typeof payload.orchestration === 'object'
       ? payload.orchestration
       : null,
@@ -681,6 +691,64 @@ export async function searchWorlds({
   });
 }
 
+export async function search({
+  cfg = {},
+  accountId = null,
+  runtimeConfig = null,
+  scope = 'mixed',
+  worldId = null,
+  agentId = null,
+  query = null,
+  limit = null,
+  sort = null,
+  page = null,
+  fetchImpl,
+  logger = console,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch is unavailable for claworld product-shell search helper');
+  }
+
+  const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
+  const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
+  const searchResult = await fetchJson(fetchImpl, `${baseUrl}/v1/search`, {
+    method: 'POST',
+    headers: buildRuntimeAuthHeaders(resolvedRuntimeConfig, {
+      accept: 'application/json',
+      'content-type': 'application/json',
+      ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
+    }),
+    body: JSON.stringify({
+      scope: normalizeText(scope, 'mixed'),
+      worldId: normalizeText(worldId, null),
+      agentId: normalizeText(agentId, null),
+      query: normalizeText(query, null),
+      sort: normalizeText(sort, null),
+      limit: limit == null ? null : normalizeInteger(limit, 0),
+      page: page == null ? null : normalizeInteger(page, 0),
+    }),
+  });
+
+  if (!searchResult.ok) {
+    logger.error?.('[claworld:product-shell] search failed', {
+      status: searchResult.status,
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      scope: normalizeText(scope, 'mixed'),
+      worldId: normalizeText(worldId, null),
+      body: searchResult.body,
+    });
+    throw createProductShellHttpError('search', searchResult, {
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      worldId: normalizeText(worldId, null),
+    });
+  }
+
+  return {
+    accountId: resolvedRuntimeConfig.accountId || accountId || null,
+    ...searchResult.body,
+  };
+}
+
 export async function joinWorld({
   cfg = {},
   accountId = null,
@@ -828,34 +896,67 @@ export async function fetchWorldCandidateFeed({
 
   const resolvedRuntimeConfig = runtimeConfig || resolveClaworldRuntimeConfig(cfg, accountId);
   const baseUrl = normalizeRelayHttpBaseUrl(resolvedRuntimeConfig.serverUrl);
-  const requestUrl = new URL(`${baseUrl}/v1/worlds/${encodeURIComponent(resolvedWorldId)}/candidates`);
-  requestUrl.searchParams.set('agentId', resolvedAgentId);
   const normalizedLimit = normalizeInteger(limit, 0);
-  if (normalizedLimit > 0) {
-    requestUrl.searchParams.set('limit', String(normalizedLimit));
-  }
-  const candidateFeed = await fetchJson(fetchImpl, requestUrl.toString(), {
+  const searchResult = await fetchJson(fetchImpl, `${baseUrl}/v1/worlds/${encodeURIComponent(resolvedWorldId)}/search`, {
+    method: 'POST',
     headers: buildRuntimeAuthHeaders(resolvedRuntimeConfig, {
       accept: 'application/json',
+      'content-type': 'application/json',
       ...(resolvedRuntimeConfig.apiKey ? { 'x-api-key': resolvedRuntimeConfig.apiKey } : {}),
     }),
+    body: JSON.stringify({
+      agentId: resolvedAgentId,
+      query: null,
+      sort: 'match',
+      limit: normalizedLimit > 0 ? normalizedLimit : null,
+    }),
   });
 
-  if (!candidateFeed.ok) {
-    logger.error?.('[claworld:product-shell] candidate feed fetch failed', {
-      status: candidateFeed.status,
+  if (!searchResult.ok) {
+    logger.error?.('[claworld:product-shell] candidate feed compatibility search failed', {
+      status: searchResult.status,
       worldId: resolvedWorldId,
       agentId: resolvedAgentId,
       accountId: resolvedRuntimeConfig.accountId || accountId || null,
-      body: candidateFeed.body,
+      body: searchResult.body,
     });
-    throw createProductShellHttpError('world_candidate_feed', candidateFeed, {
+    throw createProductShellHttpError('world_candidate_feed', searchResult, {
       accountId: resolvedRuntimeConfig.accountId || accountId || null,
       worldId: resolvedWorldId,
     });
   }
 
-  return normalizeCandidateFeedResponse(candidateFeed.body, {
+  const searchPayload = searchResult.body && typeof searchResult.body === 'object' ? searchResult.body : {};
+  const normalizedSearch = normalizeWorldMemberSearchResponse(searchPayload, {
+    accountId: resolvedRuntimeConfig.accountId || accountId || null,
+  });
+  return normalizeCandidateFeedResponse({
+    worldId: resolvedWorldId,
+    agentId: resolvedAgentId,
+    viewerMembershipId: searchPayload.viewerMembershipId,
+    generatedAt: searchPayload.generatedAt,
+    limit: normalizedSearch.limit,
+    totalCandidates: normalizedSearch.totalMatches,
+    candidateSource: searchPayload.candidateSource || 'active_memberships',
+    status: normalizedSearch.items.length > 0 ? 'feed_ready' : 'no_candidates_ready',
+    nextAction: normalizedSearch.nextAction,
+    candidates: normalizedSearch.items.map((item, index) => ({
+      candidateId: item.membershipId || `candidate_${index + 1}`,
+      sourceMembershipId: item.membershipId || null,
+      worldId: item.worldId || resolvedWorldId,
+      online: item.online === true,
+      rank: index + 1,
+      score: item.score,
+      agentCode: item.agentCode,
+      requestChat: item.requestChat,
+      profileSummary: item.profileSummary,
+      deliveryReason: {
+        summary: item.reasonSummary || item.headline || null,
+      },
+      worldFeedbackSummary: item.worldFeedbackSummary,
+      joinedAt: item.joinedAt,
+    })),
+  }, {
     worldId: resolvedWorldId,
     agentId: resolvedAgentId,
   });

package/src/openclaw/runtime/session-routing.js

@@ -0,0 +1,144 @@
+import {
+  CLAWORLD_CONTEXT_DIR,
+  CLAWORLD_JOURNAL_DIR,
+  CLAWORLD_REPORTS_DIR,
+  CLAWORLD_WORKING_MEMORY_DIR,
+  CLAWORLD_WORKING_MEMORY_FILES,
+} from './working-memory.js';
+
+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 const CLAWORLD_SESSION_KINDS = Object.freeze({
+  externalMain: 'external_main',
+  management: 'management',
+  conversation: 'conversation',
+});
+
+export const CLAWORLD_MANAGEMENT_EVENT_TYPES = Object.freeze([
+  'notification',
+  'domain_notification',
+  'management_wake',
+  'management_tick',
+  'conversation_lifecycle',
+  'platform_recommendation',
+  'ops_recommendation',
+]);
+
+export function buildManagementSessionKey(agentId = null) {
+  const normalizedAgentId = normalizeText(agentId, null);
+  return normalizedAgentId ? `management:${normalizedAgentId}` : null;
+}
+
+export function buildConversationSessionKey(conversationKey = null, fallbackSessionKey = null) {
+  const normalizedConversationKey = normalizeText(conversationKey, null);
+  if (normalizedConversationKey) return `conversation:${normalizedConversationKey}`;
+  return normalizeText(fallbackSessionKey, null);
+}
+
+export function resolveRuntimeSessionTarget(event = {}, options = {}) {
+  const payload = normalizePayload(event.payload);
+  const eventType = normalizeText(event.eventType || event.type || payload.eventType, null);
+  const targetAgentId = normalizeText(
+    event.targetAgentId,
+    normalizeText(payload.targetAgentId, normalizeText(options.targetAgentId, null)),
+  );
+  const conversationKey = normalizeText(
+    event.conversationKey,
+    normalizeText(payload.conversationKey, normalizeText(options.conversationKey, null)),
+  );
+  const providedSessionKey = normalizeText(
+    event.sessionKey,
+    normalizeText(payload.sessionKey, normalizeText(options.sessionKey, null)),
+  );
+
+  if (CLAWORLD_MANAGEMENT_EVENT_TYPES.includes(eventType)) {
+    const managementSessionKey = normalizeText(
+      options.managementSessionKey,
+      buildManagementSessionKey(targetAgentId),
+    );
+    return {
+      sessionKind: CLAWORLD_SESSION_KINDS.management,
+      target: normalizeText(options.managementTarget, 'management_session'),
+      sessionKey: managementSessionKey || providedSessionKey,
+      managementSessionKey: managementSessionKey || null,
+      conversationSessionKey: conversationKey ? buildConversationSessionKey(conversationKey) : null,
+      targetAgentId,
+      conversationKey,
+    };
+  }
+
+  const conversationSessionKey = buildConversationSessionKey(conversationKey, providedSessionKey);
+  return {
+    sessionKind: CLAWORLD_SESSION_KINDS.conversation,
+    target: normalizeText(options.sessionTarget, 'conversation_session'),
+    sessionKey: conversationSessionKey,
+    managementSessionKey: targetAgentId ? buildManagementSessionKey(targetAgentId) : null,
+    conversationSessionKey,
+    targetAgentId,
+    conversationKey,
+  };
+}
+
+export function buildAgentWorkingMemoryArtifactIndex({
+  agentId = null,
+  root = CLAWORLD_WORKING_MEMORY_DIR,
+  now = null,
+} = {}) {
+  const normalizedAgentId = normalizeText(agentId, 'unknown-agent');
+  const basePath = normalizeText(root, CLAWORLD_WORKING_MEMORY_DIR).replace(/\/+$/, '');
+  const profilePath = `${basePath}/${CLAWORLD_WORKING_MEMORY_FILES.profile}`;
+  const memoryPath = `${basePath}/${CLAWORLD_WORKING_MEMORY_FILES.memory}`;
+  const nowPath = `${basePath}/${CLAWORLD_WORKING_MEMORY_FILES.now}`;
+  return {
+    agentId: normalizedAgentId,
+    generatedAt: normalizeText(now, null),
+    workingMemoryRoot: basePath,
+    profilePath,
+    memoryPath,
+    nowPath,
+    journalPath: `${basePath}/${CLAWORLD_JOURNAL_DIR}/`,
+    reportsPath: `${basePath}/${CLAWORLD_REPORTS_DIR}/`,
+    contextPath: `${basePath}/${CLAWORLD_CONTEXT_DIR}/`,
+    requiredFiles: [profilePath, memoryPath, nowPath],
+  };
+}
+
+export function createManagementWorkingMemoryBootstrapContext({
+  agentId = null,
+  trigger = 'management_wake',
+  event = {},
+  workingMemoryRoot = CLAWORLD_WORKING_MEMORY_DIR,
+  now = null,
+} = {}) {
+  const artifactIndex = buildAgentWorkingMemoryArtifactIndex({
+    agentId,
+    root: workingMemoryRoot,
+    now,
+  });
+  return {
+    sessionKind: CLAWORLD_SESSION_KINDS.management,
+    sessionKey: buildManagementSessionKey(agentId),
+    agentId: normalizeText(agentId, null),
+    trigger: normalizeText(trigger, 'management_wake'),
+    workingMemory: artifactIndex,
+    artifactIndex,
+    bootstrapChecklist: [
+      'read PROFILE.md for autonomy policy and authorization boundaries',
+      'read MEMORY.md for durable people/world/user preference context',
+      'read NOW.md for active standing intents and report policy',
+      'load recent journal and report pointers before deciding actions',
+      'verify backend facts with public tools before acting',
+      'write journal/report evidence for important management decisions',
+    ],
+    event: normalizePayload(event),
+  };
+}