@xfxstudio/claworld 0.2.8 → 0.2.10-beta.0

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

@@ -1,5 +1,6 @@
 import { EventEmitter } from 'events';
 import WebSocket from 'ws';
+import { v4 as uuidv4 } from 'uuid';
 import { resolveClaworldRuntimeConfig } from './config-schema.js';
 import { buildRuntimeAuthHeaders } from './account-identity.js';
 import { createRelayEventProtocol } from '../protocol/relay-event-protocol.js';
@@ -43,6 +44,9 @@ function buildInboundEnvelope(message = {}) {
     eventType: data.eventType || 'delivery',
     deliveryId: data.deliveryId || null,
     sessionKey: data.sessionKey || null,
+    createdAt: data.createdAt || null,
+    updatedAt: data.updatedAt || null,
+    turnCreatedAt: data.turnCreatedAt || null,
     payload: data.payload && typeof data.payload === 'object' && !Array.isArray(data.payload)
       ? { ...data.payload }
       : {},
@@ -56,6 +60,10 @@ function normalizeOptionalText(value) {
   return normalized || null;
 }
 
+function resolveClientMessageId(value = null) {
+  return normalizeOptionalText(value) || `cmsg_${uuidv4()}`;
+}
+
 function buildReplyAckTimeoutError({ deliveryId, timeoutMs, context = {} } = {}) {
   return createRuntimeBoundaryError({
     code: 'relay_reply_ack_timeout',
@@ -68,6 +76,18 @@ function buildReplyAckTimeoutError({ deliveryId, timeoutMs, context = {} } = {})
   });
 }
 
+function buildAcceptedAckTimeoutError({ deliveryId, timeoutMs, context = {} } = {}) {
+  return createRuntimeBoundaryError({
+    code: 'relay_delivery_accept_ack_timeout',
+    category: 'transport',
+    status: 504,
+    message: `timed out waiting for relay delivery acceptance acknowledgement for ${deliveryId || 'unknown-delivery'} after ${timeoutMs}ms`,
+    publicMessage: 'relay delivery acceptance acknowledgement timed out',
+    recoverable: true,
+    context,
+  });
+}
+
 function buildReplyFallbackError({
   deliveryId,
   status,
@@ -564,7 +584,7 @@ export class ClaworldRelayClient extends EventEmitter {
     config,
     agentId,
     credential = null,
-    clientVersion = 'claworld-plugin/0.1.5',
+    clientVersion = 'claworld-plugin/0.2.8',
     sessionTarget,
     fallbackTarget,
   } = {}) {
@@ -655,6 +675,34 @@ export class ClaworldRelayClient extends EventEmitter {
     this.send({ type: 'heartbeat' });
   }
 
+  sendAccepted({ deliveryId, sessionKey, source = 'runtime_dispatch' } = {}) {
+    const normalizedDeliveryId = normalizeOptionalText(deliveryId);
+    if (!normalizedDeliveryId) {
+      throw createRuntimeBoundaryError({
+        code: 'relay_delivery_id_required',
+        category: 'input',
+        status: 400,
+        message: 'deliveryId is required to acknowledge relay delivery acceptance',
+        publicMessage: 'deliveryId is required',
+        recoverable: true,
+      });
+    }
+    const envelope = {
+      deliveryId: normalizedDeliveryId,
+      sessionKey: normalizeOptionalText(sessionKey) || null,
+      source: normalizeOptionalText(source) || 'runtime_dispatch',
+    };
+    this.send({
+      type: 'accepted',
+      deliveryId: envelope.deliveryId,
+      sessionKey: envelope.sessionKey,
+      payload: {
+        source: envelope.source,
+      },
+    });
+    return envelope;
+  }
+
   sendReply({ deliveryId, sessionKey, replyText, source = 'subagent' } = {}) {
     const envelope = this.outbound.createReplyEnvelope({
       deliveryId,
@@ -791,6 +839,85 @@ export class ClaworldRelayClient extends EventEmitter {
     });
   }
 
+  waitForAcceptedAck({ deliveryId, timeoutMs = DEFAULT_REPLY_ACK_TIMEOUT_MS } = {}) {
+    const normalizedDeliveryId = normalizeOptionalText(deliveryId);
+    if (!normalizedDeliveryId) {
+      return Promise.reject(createRuntimeBoundaryError({
+        code: 'relay_delivery_id_required',
+        category: 'input',
+        status: 400,
+        message: 'deliveryId is required to wait for relay delivery acceptance acknowledgement',
+        publicMessage: 'deliveryId is required',
+        recoverable: true,
+      }));
+    }
+
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let timeout = null;
+
+      const cleanup = () => {
+        if (timeout) clearTimeout(timeout);
+        this.off('delivery.accepted', onAccepted);
+        this.off('disconnect', onDisconnect);
+        this.off('close', onDisconnect);
+      };
+
+      const settleResolve = (value) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve(value);
+      };
+
+      const settleReject = (error) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(error);
+      };
+
+      const onAccepted = (message = {}) => {
+        const acceptedDeliveryId = normalizeOptionalText(message?.data?.acceptedDeliveryId);
+        if (acceptedDeliveryId !== normalizedDeliveryId) return;
+        settleResolve(message);
+      };
+
+      const onDisconnect = (info = {}) => {
+        settleReject(createRuntimeBoundaryError({
+          code: 'relay_delivery_accept_ack_disconnected',
+          category: 'transport',
+          status: 502,
+          message: `relay websocket closed before delivery acceptance acknowledgement for ${normalizedDeliveryId}`,
+          publicMessage: 'relay websocket closed before delivery acceptance acknowledgement',
+          recoverable: true,
+          context: this.buildBoundaryContext({
+            stage: 'delivery_accept_ack_wait',
+            deliveryId: normalizedDeliveryId,
+            closeCode: info?.code ?? null,
+            closeReason: info?.reason || null,
+          }),
+        }));
+      };
+
+      this.on('delivery.accepted', onAccepted);
+      this.on('disconnect', onDisconnect);
+      this.on('close', onDisconnect);
+
+      timeout = setTimeout(() => {
+        settleReject(buildAcceptedAckTimeoutError({
+          deliveryId: normalizedDeliveryId,
+          timeoutMs,
+          context: this.buildBoundaryContext({
+            stage: 'delivery_accept_ack_wait',
+            deliveryId: normalizedDeliveryId,
+          }),
+        }));
+      }, timeoutMs);
+      if (typeof timeout.unref === 'function') timeout.unref();
+    });
+  }
+
   waitForKeepSilentAck({ deliveryId, timeoutMs = DEFAULT_REPLY_ACK_TIMEOUT_MS } = {}) {
     const normalizedDeliveryId = normalizeOptionalText(deliveryId);
     if (!normalizedDeliveryId) {
@@ -897,6 +1024,31 @@ export class ClaworldRelayClient extends EventEmitter {
     };
   }
 
+  async acceptDeliveryHttp({ deliveryId, sessionKey = null, source = 'runtime_dispatch' } = {}) {
+    const normalizedDeliveryId = normalizeOptionalText(deliveryId);
+    const result = await this.requestJson(`/v1/deliveries/${encodeURIComponent(normalizedDeliveryId)}/accepted`, {
+      method: 'POST',
+      headers: buildRuntimeAuthHeaders(this.runtimeConfig, { 'content-type': 'application/json' }),
+      body: JSON.stringify({
+        fromAgentId: this.boundAgentId,
+        sessionKey: normalizeOptionalText(sessionKey) || null,
+        source: normalizeOptionalText(source) || 'runtime_dispatch',
+      }),
+    }, {
+      code: 'relay_delivery_accept_fallback_failed',
+      message: 'failed to submit relay delivery acceptance fallback',
+      publicMessage: 'failed to submit relay delivery acceptance fallback',
+    });
+    return {
+      ...result,
+      envelope: {
+        deliveryId: normalizedDeliveryId,
+        sessionKey: normalizeOptionalText(sessionKey) || null,
+        source: normalizeOptionalText(source) || 'runtime_dispatch',
+      },
+    };
+  }
+
   async sendReplyAndWaitForAck({
     deliveryId,
     sessionKey,
@@ -984,6 +1136,75 @@ export class ClaworldRelayClient extends EventEmitter {
     }
   }
 
+  async sendAcceptedAndWaitForAck({
+    deliveryId,
+    sessionKey,
+    source = 'runtime_dispatch',
+    timeoutMs = DEFAULT_REPLY_ACK_TIMEOUT_MS,
+    httpFallback = true,
+  } = {}) {
+    const envelope = this.sendAccepted({
+      deliveryId,
+      sessionKey,
+      source,
+    });
+
+    try {
+      const ack = await this.waitForAcceptedAck({
+        deliveryId: envelope.deliveryId,
+        timeoutMs,
+      });
+      return {
+        ok: true,
+        envelope,
+        ack,
+        transport: 'websocket',
+        fallbackUsed: false,
+      };
+    } catch (error) {
+      if (!httpFallback) throw error;
+
+      this.logger.warn?.('[claworld:relay-client] delivery acceptance websocket acknowledgement failed; attempting HTTP fallback', {
+        accountId: this.runtimeConfig?.accountId || null,
+        agentId: this.boundAgentId,
+        deliveryId: envelope.deliveryId,
+        sessionKey: envelope.sessionKey,
+        error: error?.message || String(error),
+      });
+
+      const fallbackResult = await this.acceptDeliveryHttp({
+        deliveryId: envelope.deliveryId,
+        sessionKey: envelope.sessionKey,
+        source: envelope.source,
+      });
+
+      if (fallbackResult.status >= 200 && fallbackResult.status < 300) {
+        return {
+          ok: true,
+          envelope,
+          ack: {
+            event: 'delivery.accepted',
+            data: fallbackResult.body,
+          },
+          transport: 'http',
+          fallbackUsed: true,
+        };
+      }
+
+      throw buildReplyFallbackError({
+        deliveryId: envelope.deliveryId,
+        status: fallbackResult.status,
+        body: fallbackResult.body,
+        context: this.buildBoundaryContext({
+          stage: 'delivery_accept_fallback',
+          deliveryId: envelope.deliveryId,
+          sessionKey: envelope.sessionKey,
+          fallbackFrom: error?.code || error?.message || null,
+        }),
+      });
+    }
+  }
+
   async keepDeliverySilentHttp({ deliveryId, reason = null, source = 'openclaw-autochain' } = {}) {
     const normalizedDeliveryId = normalizeOptionalText(deliveryId);
     const result = await this.requestJson(`/v1/deliveries/${encodeURIComponent(normalizedDeliveryId)}/kept-silent`, {
@@ -1096,27 +1317,20 @@ export class ClaworldRelayClient extends EventEmitter {
     }
   }
 
-  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;
-
+  async createChatRequest({ fromAgentId, targetAgentId, requestContext = {} } = {}) {
     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,
-        targetAgentId: target.body?.agentId || target.body?.id || null,
+        targetAgentId,
         kickoffBrief: normalized.kickoffBrief || null,
         openingMessage: normalized.openingMessage || null,
         worldId: normalized.conversation?.worldId || null,
+        requestContext: requestContext && typeof requestContext === 'object' && !Array.isArray(requestContext)
+          ? requestContext
+          : undefined,
       }),
     }, {
       code: 'relay_request_create_failed',
@@ -1161,16 +1375,21 @@ export class ClaworldRelayClient extends EventEmitter {
     });
   }
 
-  async deliverMessage({ fromAgentId, toAddress, payload = {}, conversation = {} } = {}) {
-    return await this.requestJson('/v1/messages', {
+  async deliverMessage({ fromAgentId, targetAgentId, clientMessageId = null, payload = {}, conversation = {} } = {}) {
+    const resolvedClientMessageId = resolveClientMessageId(clientMessageId);
+    const result = await this.requestJson('/v1/messages', {
       method: 'POST',
       headers: buildRuntimeAuthHeaders(this.runtimeConfig, { 'content-type': 'application/json' }),
-      body: JSON.stringify({ fromAgentId, toAddress, payload, conversation }),
+      body: JSON.stringify({ fromAgentId, targetAgentId, clientMessageId: resolvedClientMessageId, payload, conversation }),
     }, {
       code: 'relay_message_delivery_failed',
       message: 'failed to deliver relay message',
       publicMessage: 'failed to deliver relay message',
     });
+    return {
+      ...result,
+      clientMessageId: resolvedClientMessageId,
+    };
   }
 
   waitFor(eventNameOrPredicate, timeoutMs = 8000) {
@@ -1198,7 +1417,7 @@ export class ClaworldRelayClient extends EventEmitter {
     });
   }
 
-  async establishConversation({ fromAgentId, toAddress, requestContext = {}, openingPayload = {} } = {}) {
+  async establishConversation({ fromAgentId, targetAgentId, requestContext = {}, openingPayload = {} } = {}) {
     const normalizedRequestContext = requestContext && typeof requestContext === 'object' && !Array.isArray(requestContext)
       ? { ...requestContext }
       : {};
@@ -1214,7 +1433,7 @@ export class ClaworldRelayClient extends EventEmitter {
 
     const requestResult = await this.createChatRequest({
       fromAgentId,
-      toAddress,
+      targetAgentId,
       requestContext: normalizedRequestContext,
     });
     if (requestResult.status !== 201) {

package/src/openclaw/runtime/backend-error-context.js

@@ -0,0 +1,91 @@
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function normalizeFieldError(fieldError = {}) {
+  const fieldId = normalizeText(fieldError.fieldId, null);
+  const message = normalizeText(fieldError.message, null);
+  const code = normalizeText(fieldError.code, null);
+  if (!fieldId && !message && !code) return null;
+  return {
+    ...(fieldId ? { fieldId } : {}),
+    ...(message ? { message } : {}),
+    ...(code ? { code } : {}),
+  };
+}
+
+function normalizeMissingField(field = {}) {
+  const fieldId = normalizeText(field.fieldId, null);
+  const label = normalizeText(field.label, null);
+  const description = normalizeText(field.description, null);
+  const message = normalizeText(field.message, null);
+  const code = normalizeText(field.code, null);
+  if (!fieldId && !label && !description && !message && !code) return null;
+  return {
+    ...(fieldId ? { fieldId } : {}),
+    ...(label ? { label } : {}),
+    ...(description ? { description } : {}),
+    ...(message ? { message } : {}),
+    ...(code ? { code } : {}),
+  };
+}
+
+function normalizePublicIdentity(publicIdentity = {}) {
+  const status = normalizeText(publicIdentity.status, null);
+  const displayName = normalizeText(publicIdentity.displayName, null);
+  const code = normalizeText(publicIdentity.code, null);
+  const displayIdentity = normalizeText(publicIdentity.displayIdentity, null);
+  const confirmedAt = normalizeText(publicIdentity.confirmedAt, null);
+  const updatedAt = normalizeText(publicIdentity.updatedAt, null);
+  if (!status && !displayName && !code && !displayIdentity && !confirmedAt && !updatedAt) return null;
+  return {
+    ...(status ? { status } : {}),
+    ...(displayName ? { displayName } : {}),
+    ...(code ? { code } : {}),
+    ...(displayIdentity ? { displayIdentity } : {}),
+    ...(confirmedAt ? { confirmedAt } : {}),
+    ...(updatedAt ? { updatedAt } : {}),
+  };
+}
+
+export function normalizeBackendFieldError(fieldError = {}) {
+  return normalizeFieldError(fieldError);
+}
+
+export function normalizeBackendMissingField(field = {}) {
+  return normalizeMissingField(field);
+}
+
+export function normalizeBackendPublicIdentity(publicIdentity = {}) {
+  return normalizePublicIdentity(publicIdentity);
+}
+
+export function extractBackendErrorContext(payload = {}) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return {};
+
+  const backendCode = normalizeText(payload.error, null);
+  const backendMessage = normalizeText(payload.message, null);
+  const requiredAction = normalizeText(payload.requiredAction, null);
+  const nextAction = normalizeText(payload.nextAction, null);
+  const nextTool = normalizeText(payload.nextTool, null);
+  const fieldErrors = Array.isArray(payload.fieldErrors)
+    ? payload.fieldErrors.map((fieldError) => normalizeFieldError(fieldError)).filter(Boolean)
+    : [];
+  const missingFields = Array.isArray(payload.missingFields)
+    ? payload.missingFields.map((field) => normalizeMissingField(field)).filter(Boolean)
+    : [];
+  const publicIdentity = normalizePublicIdentity(payload.publicIdentity);
+
+  return {
+    ...(backendCode ? { backendCode } : {}),
+    ...(backendMessage ? { backendMessage } : {}),
+    ...(requiredAction ? { requiredAction } : {}),
+    ...(nextAction ? { nextAction } : {}),
+    ...(nextTool ? { nextTool } : {}),
+    ...(fieldErrors.length > 0 ? { fieldErrors } : {}),
+    ...(missingFields.length > 0 ? { missingFields } : {}),
+    ...(publicIdentity ? { publicIdentity } : {}),
+  };
+}

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

@@ -114,7 +114,6 @@ export async function submitFeedbackReport({
         turnId: normalizeText(normalizedContext.turnId, null),
         deliveryId: normalizeText(normalizedContext.deliveryId, null),
         targetAgentId: normalizeText(normalizedContext.targetAgentId, null),
-        targetAgentCode: normalizeText(normalizedContext.targetAgentCode, null),
         tags: normalizeStringList(normalizedContext.tags),
         metadata: normalizeObject(normalizedContext.metadata),
       },
@@ -128,7 +127,7 @@ export async function submitFeedbackReport({
         accountId: normalizeText(resolvedRuntimeConfig.accountId, normalizeText(accountId, null)),
         serverUrl: baseUrl,
         relayAgentId: resolvedAgentId,
-        defaultToAddress: normalizeText(resolvedRuntimeConfig.relay?.defaultToAddress, null),
+        defaultTargetAgentId: normalizeText(resolvedRuntimeConfig.relay?.defaultTargetAgentId, null),
       },
     }),
   });

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

@@ -1,6 +1,7 @@
 import { resolveClaworldRuntimeConfig } from '../plugin/config-schema.js';
 import { buildRuntimeAuthHeaders } from '../plugin/account-identity.js';
 import { createRuntimeBoundaryError } from '../../lib/runtime-errors.js';
+import { extractBackendErrorContext } from './backend-error-context.js';
 import {
   buildCandidateDeliverySummary as buildBackendCandidateDeliverySummary,
   buildWorldSelectionPrompt as buildBackendWorldSelectionPrompt,
@@ -337,6 +338,15 @@ function normalizeCandidate(candidate = {}, index = 0) {
       ? candidate.compatibilitySignals.map((signal, signalIndex) => normalizeCompatibilitySignal(signal, signalIndex))
       : [],
     deliveryReason: normalizeDeliveryReason(candidate.deliveryReason),
+    worldFeedbackSummary: candidate.worldFeedbackSummary && typeof candidate.worldFeedbackSummary === 'object'
+      ? {
+          likesReceived: normalizeInteger(candidate.worldFeedbackSummary.likesReceived, 0),
+          dislikesReceived: normalizeInteger(candidate.worldFeedbackSummary.dislikesReceived, 0),
+        }
+      : {
+          likesReceived: 0,
+          dislikesReceived: 0,
+        },
     expiresAt: normalizeText(candidate.expiresAt, null),
     joinedAt: normalizeText(candidate.joinedAt, null),
     rank: normalizedRank == null ? null : Math.max(1, Math.trunc(normalizedRank)),
@@ -437,7 +447,6 @@ function normalizeWorldSearchItem(item = {}, index = 0) {
     worldId: normalizeText(item.worldId, 'unknown-world'),
     displayName: normalizeText(item.displayName, `Player ${index + 1}`),
     headline: normalizeText(item.headline, null),
-    address: normalizeText(item.address, null),
     online: item.online === true,
     connectedAt: normalizeText(item.connectedAt, null),
     lastHeartbeatAt: normalizeText(item.lastHeartbeatAt, null),
@@ -450,6 +459,15 @@ function normalizeWorldSearchItem(item = {}, index = 0) {
     reasonSummary: normalizeText(item.reasonSummary, ''),
     joinedAt: normalizeText(item.joinedAt, null),
     profileSummary: normalizeCandidateProfileSummary(item.profileSummary),
+    worldFeedbackSummary: item.worldFeedbackSummary && typeof item.worldFeedbackSummary === 'object'
+      ? {
+          likesReceived: normalizeInteger(item.worldFeedbackSummary.likesReceived, 0),
+          dislikesReceived: normalizeInteger(item.worldFeedbackSummary.dislikesReceived, 0),
+        }
+      : {
+          likesReceived: 0,
+          dislikesReceived: 0,
+        },
   };
 }
 
@@ -686,8 +704,7 @@ function createProductShellHttpError(action, response, { accountId = null, world
       accountId,
       ...(worldId ? { worldId } : {}),
       httpStatus: response?.status ?? 500,
-      backendCode,
-      backendMessage,
+      ...extractBackendErrorContext(response?.body),
     },
   });
 }
@@ -776,7 +793,10 @@ export async function fetchWorldDetail({
       accountId: resolvedRuntimeConfig.accountId || accountId || null,
       body: detail.body,
     });
-    throw new Error(`claworld product-shell world detail fetch failed: ${detail.status}`);
+    throw createProductShellHttpError('world_detail', detail, {
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      worldId: resolvedWorldId,
+    });
   }
 
   return normalizeWorldDetail(detail.body);
@@ -830,7 +850,10 @@ export async function joinWorld({
       accountId: resolvedRuntimeConfig.accountId || accountId || null,
       body: joinResult.body,
     });
-    throw new Error(`claworld product-shell world join failed: ${joinResult.status}`);
+    throw createProductShellHttpError('world_join', joinResult, {
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      worldId: resolvedWorldId,
+    });
   }
 
   return normalizeWorldJoinResponse(joinResult.body, {
@@ -890,7 +913,10 @@ export async function fetchWorldSearch({
       accountId: resolvedRuntimeConfig.accountId || accountId || null,
       body: searchResult.body,
     });
-    throw new Error(`claworld product-shell world search failed: ${searchResult.status}`);
+    throw createProductShellHttpError('world_search', searchResult, {
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      worldId: resolvedWorldId,
+    });
   }
 
   return normalizeWorldSearchResponse(searchResult.body, {
@@ -950,7 +976,10 @@ export async function submitWorldSearch({
       accountId: resolvedRuntimeConfig.accountId || accountId || null,
       body: searchResult.body,
     });
-    throw new Error(`claworld product-shell world search failed: ${searchResult.status}`);
+    throw createProductShellHttpError('world_search', searchResult, {
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      worldId: resolvedWorldId,
+    });
   }
 
   if (searchResult.status === 409) {
@@ -1095,7 +1124,10 @@ export async function fetchWorldCandidateFeed({
       accountId: resolvedRuntimeConfig.accountId || accountId || null,
       body: candidateFeed.body,
     });
-    throw new Error(`claworld product-shell candidate feed failed: ${candidateFeed.status}`);
+    throw createProductShellHttpError('world_candidate_feed', candidateFeed, {
+      accountId: resolvedRuntimeConfig.accountId || accountId || null,
+      worldId: resolvedWorldId,
+    });
   }
 
   return normalizeCandidateFeedResponse(candidateFeed.body, {
@@ -1136,7 +1168,9 @@ export async function resolveWorldSelectionFlow({
           accountId: resolvedRuntimeConfig.accountId || accountId || null,
           body: worlds.body,
         });
-        throw new Error(`claworld product-shell world fetch failed: ${worlds.status}`);
+        throw createProductShellHttpError('world_directory', worlds, {
+          accountId: resolvedRuntimeConfig.accountId || accountId || null,
+        });
       }
 
       return buildPostSetupWorldDirectory(worlds.body, {