@xfxstudio/claworld 2026.4.16-testing.1 → 2026.4.16-testing.2

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

@@ -0,0 +1,191 @@
+import { renderAcceptedChatKickoffMarkdown } from './agent-readable-markdown.js';
+
+export const ACCEPTED_CHAT_KICKOFF_PAYLOAD_KIND = 'accepted_chat_kickoff';
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+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;
+  }
+}
+
+function normalizeKickoffPayload(input) {
+  return cloneJsonObject(input);
+}
+
+function normalizeKickoffSource(value, fallback = 'chat_request_brief') {
+  return normalizeText(value, fallback);
+}
+
+export function projectKickoffBrief(input = null) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  const normalized = createKickoffBrief({
+    text: input.text,
+    payload: input.payload,
+    source: input.source,
+  });
+  if (!normalized) return null;
+
+  const payload = normalized.payload && typeof normalized.payload === 'object' && !Array.isArray(normalized.payload)
+    ? cloneJsonObject(normalized.payload)
+    : null;
+  if (payload?.text === normalized.text) delete payload.text;
+  if (payload?.source === normalized.source) delete payload.source;
+
+  return {
+    ...(normalized.text ? { text: normalized.text } : {}),
+    ...(payload && Object.keys(payload).length > 0 ? { payload } : {}),
+    ...(normalized.source && normalized.source !== 'chat_request_brief' ? { source: normalized.source } : {}),
+  };
+}
+
+export function createKickoffBrief({
+  text = null,
+  payload = null,
+  source = 'chat_request_brief',
+} = {}) {
+  const normalizedPayload = normalizeKickoffPayload(payload);
+  const normalizedText = normalizeText(text, normalizeText(normalizedPayload?.text, null));
+  if (!normalizedText && !normalizedPayload) return null;
+  const hasPayloadText = typeof normalizedPayload?.text === 'string' && normalizedPayload.text.trim().length > 0;
+  return {
+    ...(normalizedText ? { text: normalizedText } : {}),
+    ...(normalizedPayload ? {
+      payload: {
+        ...normalizedPayload,
+        ...(normalizedText && !hasPayloadText ? { text: normalizedText } : {}),
+      },
+    } : {}),
+    source: normalizeKickoffSource(source),
+  };
+}
+
+export function resolveStoredKickoffBrief(requestContext = {}) {
+  if (!requestContext || typeof requestContext !== 'object' || Array.isArray(requestContext)) return null;
+
+  const kickoffBrief = requestContext.kickoffBrief && typeof requestContext.kickoffBrief === 'object' && !Array.isArray(requestContext.kickoffBrief)
+    ? requestContext.kickoffBrief
+    : null;
+  if (kickoffBrief) {
+    return createKickoffBrief({
+      text: kickoffBrief.text,
+      payload: kickoffBrief.payload,
+      source: kickoffBrief.source,
+    });
+  }
+
+  return createKickoffBrief({
+    text: normalizeText(requestContext.openingPayload?.text, normalizeText(requestContext.message, null)),
+    payload: requestContext.openingPayload,
+    source: requestContext.openingPayload?.source || 'chat_request_opening',
+  });
+}
+
+export function resolveAcceptedChatKickoffViewer(bundle = {}, {
+  localAgentId = null,
+  fallback = 'recipient',
+} = {}) {
+  const normalizedLocalAgentId = normalizeText(localAgentId, null);
+  const participants = bundle?.participants && typeof bundle.participants === 'object' && !Array.isArray(bundle.participants)
+    ? bundle.participants
+    : {};
+  const senderAgentId = normalizeText(participants.sender?.agentId, null);
+  const recipientAgentId = normalizeText(participants.recipient?.agentId, null);
+
+  if (normalizedLocalAgentId && normalizedLocalAgentId === senderAgentId) return 'sender';
+  if (normalizedLocalAgentId && normalizedLocalAgentId === recipientAgentId) return 'recipient';
+  return fallback === 'sender' ? 'sender' : 'recipient';
+}
+
+function buildAcceptedChatKickoffRuntimeContext(bundle = {}, { viewer = 'recipient' } = {}) {
+  const resolvedViewer = viewer === 'sender' ? 'sender' : 'recipient';
+  const requestContext = bundle.requestContext && typeof bundle.requestContext === 'object' && !Array.isArray(bundle.requestContext)
+    ? bundle.requestContext
+    : {};
+  const request = bundle.request && typeof bundle.request === 'object' && !Array.isArray(bundle.request)
+    ? bundle.request
+    : {};
+  const brief = requestContext.brief && typeof requestContext.brief === 'object' && !Array.isArray(requestContext.brief)
+    ? requestContext.brief
+    : request.brief && typeof request.brief === 'object' && !Array.isArray(request.brief)
+      ? request.brief
+      : {};
+
+  return {
+    viewer: resolvedViewer,
+    text: formatAcceptedChatKickoffMessage(bundle, { viewer: resolvedViewer }),
+    briefText: normalizeText(brief.text, null),
+  };
+}
+
+export function readAcceptedChatKickoffRuntimeContext(bundle = {}, { viewer = 'recipient' } = {}) {
+  const resolvedViewer = viewer === 'sender' ? 'sender' : 'recipient';
+  const requestContext = bundle.requestContext && typeof bundle.requestContext === 'object' && !Array.isArray(bundle.requestContext)
+    ? bundle.requestContext
+    : {};
+  const request = bundle.request && typeof bundle.request === 'object' && !Array.isArray(bundle.request)
+    ? bundle.request
+    : {};
+  const brief = requestContext.brief && typeof requestContext.brief === 'object' && !Array.isArray(requestContext.brief)
+    ? requestContext.brief
+    : request.brief && typeof request.brief === 'object' && !Array.isArray(request.brief)
+      ? request.brief
+      : {};
+  const runtimeContext = bundle.runtimeContext && typeof bundle.runtimeContext === 'object' && !Array.isArray(bundle.runtimeContext)
+    ? bundle.runtimeContext
+    : {};
+  const candidate = runtimeContext[resolvedViewer] && typeof runtimeContext[resolvedViewer] === 'object' && !Array.isArray(runtimeContext[resolvedViewer])
+    ? runtimeContext[resolvedViewer]
+    : null;
+  if (!candidate) return null;
+
+  const text = normalizeText(candidate.text, null);
+  if (!text) return null;
+
+  return {
+    viewer: resolvedViewer,
+    text,
+    briefText: normalizeText(candidate.briefText, normalizeText(brief.text, null)),
+  };
+}
+
+export function createAcceptedChatKickoffRuntimeContext(bundle = {}, { viewer = 'recipient' } = {}) {
+  return readAcceptedChatKickoffRuntimeContext(bundle, { viewer })
+    || buildAcceptedChatKickoffRuntimeContext(bundle, { viewer });
+}
+
+export function createAcceptedChatKickoffRuntimeContexts(bundle = {}) {
+  return {
+    sender: buildAcceptedChatKickoffRuntimeContext(bundle, { viewer: 'sender' }),
+    recipient: buildAcceptedChatKickoffRuntimeContext(bundle, { viewer: 'recipient' }),
+  };
+}
+
+export function createAcceptedChatKickoffRuntimeContextForAgent(bundle = {}, {
+  localAgentId = null,
+  fallback = 'recipient',
+} = {}) {
+  return createAcceptedChatKickoffRuntimeContext(bundle, {
+    viewer: resolveAcceptedChatKickoffViewer(bundle, {
+      localAgentId,
+      fallback,
+    }),
+  });
+}
+
+export function formatAcceptedChatKickoffMessage(bundle = {}, { viewer = 'recipient' } = {}) {
+  return renderAcceptedChatKickoffMarkdown(
+    cloneJsonObject(bundle) || {},
+    { viewer: viewer === 'sender' ? 'sender' : 'recipient' },
+  );
+}

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/lib/runtime-errors.js

@@ -0,0 +1,149 @@
+const DEFAULT_STATUS_BY_CATEGORY = {
+  auth: 401,
+  bootstrap: 500,
+  config: 400,
+  conflict: 409,
+  input: 400,
+  policy: 403,
+  runtime: 500,
+  transport: 502,
+};
+
+function inferFallbackCode(error) {
+  const code = typeof error?.code === 'string' ? error.code.trim() : '';
+  if (!code) return null;
+  return code.toLowerCase();
+}
+
+function normalizeContext(context = null) {
+  if (!context || typeof context !== 'object' || Array.isArray(context)) return null;
+  return context;
+}
+
+export class RuntimeBoundaryError extends Error {
+  constructor({
+    code = 'internal_runtime_error',
+    category = 'runtime',
+    status = null,
+    message = 'internal runtime error',
+    publicMessage = null,
+    recoverable = false,
+    context = null,
+    cause = null,
+  } = {}) {
+    super(message, cause ? { cause } : undefined);
+    this.name = 'RuntimeBoundaryError';
+    this.code = code;
+    this.category = category;
+    this.status = status ?? DEFAULT_STATUS_BY_CATEGORY[category] ?? 500;
+    this.publicMessage = publicMessage || null;
+    this.recoverable = Boolean(recoverable);
+    this.context = normalizeContext(context);
+  }
+}
+
+export function createRuntimeBoundaryError(options = {}) {
+  return new RuntimeBoundaryError(options);
+}
+
+export function isRuntimeBoundaryError(error) {
+  return error instanceof RuntimeBoundaryError
+    || (
+      error?.name === 'RuntimeBoundaryError'
+      && typeof error?.code === 'string'
+      && typeof error?.category === 'string'
+    );
+}
+
+export function normalizeRuntimeBoundaryError(error, fallback = {}) {
+  if (isRuntimeBoundaryError(error)) {
+    if (fallback?.context && !error.context) {
+      error.context = normalizeContext(fallback.context);
+    }
+    return error;
+  }
+
+  return new RuntimeBoundaryError({
+    code: fallback.code || inferFallbackCode(error) || 'internal_runtime_error',
+    category: fallback.category || 'runtime',
+    status: fallback.status ?? null,
+    message: fallback.message || error?.message || String(error || 'internal runtime error'),
+    publicMessage: fallback.publicMessage || null,
+    recoverable: fallback.recoverable === true,
+    context: fallback.context || null,
+    cause: error || null,
+  });
+}
+
+function serializeCause(error) {
+  const cause = error?.cause;
+  if (!cause || cause === error) return null;
+  return {
+    name: cause?.name || null,
+    code: typeof cause?.code === 'string' ? cause.code : null,
+    message: cause?.message || String(cause),
+  };
+}
+
+export function serializeRuntimeBoundaryError(error, { includeStack = false } = {}) {
+  const normalized = normalizeRuntimeBoundaryError(error);
+  const payload = {
+    name: normalized.name,
+    code: normalized.code,
+    category: normalized.category,
+    status: normalized.status,
+    recoverable: normalized.recoverable,
+    message: normalized.message,
+    publicMessage: normalized.publicMessage || null,
+    context: normalized.context || null,
+    cause: serializeCause(normalized),
+  };
+  if (includeStack && normalized.stack) {
+    payload.stack = normalized.stack;
+  }
+  return payload;
+}
+
+export function buildPublicErrorPayload(
+  error,
+  {
+    errorType = 'internal_runtime_error',
+    fallbackMessage = 'internal runtime error',
+    exposeMessage = false,
+    extra = null,
+  } = {},
+) {
+  const normalized = normalizeRuntimeBoundaryError(error, {
+    code: errorType,
+    category: 'runtime',
+    message: fallbackMessage,
+  });
+
+  return {
+    error: errorType,
+    code: normalized.code,
+    category: normalized.category,
+    recoverable: normalized.recoverable,
+    message: exposeMessage ? (normalized.publicMessage || normalized.message) : (normalized.publicMessage || fallbackMessage),
+    ...(extra && typeof extra === 'object' ? extra : {}),
+  };
+}
+
+export function logRuntimeBoundary(
+  logger,
+  label,
+  error,
+  context = null,
+  { includeStack = true, fallback = null } = {},
+) {
+  const mergedContext = {
+    ...normalizeContext(fallback?.context || null),
+    ...normalizeContext(context),
+  };
+  const normalized = normalizeRuntimeBoundaryError(error, {
+    ...(fallback || {}),
+    context: Object.keys(mergedContext).length > 0 ? mergedContext : null,
+  });
+  logger?.error?.(label, serializeRuntimeBoundaryError(normalized, { includeStack }));
+  return normalized;
+}

package/src/openclaw/index.js

@@ -0,0 +1,51 @@
+export { createClaworldChannelPlugin, claworldChannelPluginScaffold } from './plugin/claworld-channel-plugin.js';
+export { registerClaworldPlugin, registerClaworldPluginFull } from './plugin/register.js';
+export {
+  CLAWORLD_CHANNEL_ID,
+  claworldChannelConfigSchema,
+  claworldChannelConfigJsonSchema,
+  validateClaworldChannelConfig,
+  inspectClaworldChannelAccount,
+  resolveClaworldChannelAccount,
+  resolveClaworldRuntimeConfig,
+  listClaworldAccountIds,
+  defaultClaworldAccountId,
+  LOCAL_AGENT_BOOTSTRAP_SCHEMA,
+  LOCAL_AGENT_BOOTSTRAP_REQUIRED,
+} from './plugin/config-schema.js';
+export { createClaworldLifecycleManager } from './plugin/lifecycle.js';
+export { getClaworldRuntime, setClaworldRuntime } from './plugin/runtime.js';
+export {
+  ClaworldRelayClient,
+  createClaworldRelayClient,
+  normalizeRelayWebSocketUrl,
+} from './plugin/relay-client.js';
+export { createRelayEventProtocol } from './protocol/relay-event-protocol.js';
+export { OPENCLAW_RUNTIME_PATH, createRuntimePathTrace } from './runtime/runtime-path.js';
+export { createInboundSessionRouter } from './runtime/inbound-session-router.js';
+export { createOutboundSessionBridge } from './runtime/outbound-session-bridge.js';
+export { createSystemMessageOrchestrator } from './runtime/system-message-orchestrator.js';
+export { createCanonicalResultBuilder } from './runtime/canonical-result-builder.js';
+export { createDemoSessionBootstrap } from './runtime/demo-session-bootstrap.js';
+export {
+  createModeratedWorld,
+  fetchOwnedWorlds,
+  manageModeratedWorld,
+} from './runtime/world-moderation-helper.js';
+export {
+  fetchWorldMemberships,
+  fetchWorldMembership,
+  updateWorldMembershipProfile,
+  leaveWorldMembership,
+} from './runtime/world-membership-helper.js';
+export {
+  buildPostSetupWorldDirectory,
+  buildWorldSelectionPrompt,
+  resolveWorldSelection,
+  fetchWorldDetail,
+  joinWorld,
+  fetchWorldCandidateFeed,
+  buildCandidateDeliverySummary,
+  resolveWorldSelectionFlow,
+} from './runtime/product-shell-helper.js';
+export { submitFeedbackReport } from './runtime/feedback-helper.js';

package/src/openclaw/plugin/account-identity.js

@@ -0,0 +1,73 @@
+import {
+  CLAWORLD_PLUGIN_CURRENT_VERSION,
+  CLAWORLD_PLUGIN_VERSION_HEADER,
+} from '../plugin-version.js';
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+export function normalizeRuntimeRegistration(candidate = {}) {
+  const registration = candidate.registration && typeof candidate.registration === 'object'
+    ? candidate.registration
+    : {};
+  const legacyLocalAgent = candidate.localAgent && typeof candidate.localAgent === 'object'
+    ? candidate.localAgent
+    : {};
+  const enabled = registration.enabled === true || legacyLocalAgent.enabled === true;
+
+  if (!enabled) return { enabled: false };
+
+  return {
+    enabled: true,
+    displayName: normalizeText(registration.displayName, normalizeText(legacyLocalAgent.displayName, null)),
+  };
+}
+
+export function resolveRuntimeAppToken(candidate = {}) {
+  return normalizeText(
+    candidate.appToken,
+    normalizeText(
+      candidate.relay?.appToken,
+      normalizeText(candidate.relay?.credentialToken, null),
+    ),
+  );
+}
+
+export function applyRuntimeIdentity(runtimeConfig = {}, { agentId = null, appToken = null } = {}) {
+  const resolvedAppToken = normalizeText(appToken, resolveRuntimeAppToken(runtimeConfig));
+  const registration = normalizeRuntimeRegistration(runtimeConfig);
+  const relay = runtimeConfig.relay && typeof runtimeConfig.relay === 'object'
+    ? runtimeConfig.relay
+    : {};
+
+  return {
+    ...runtimeConfig,
+    appToken: resolvedAppToken,
+    registration,
+    localAgent: registration,
+    relay: {
+      ...relay,
+      agentId: normalizeText(agentId, normalizeText(relay.agentId, null)),
+      appToken: resolvedAppToken,
+      credentialToken: resolvedAppToken,
+      defaultTargetAgentId: normalizeText(relay.defaultTargetAgentId, null),
+    },
+  };
+}
+
+export function buildRuntimeAuthHeaders(runtimeConfig = {}, headers = {}) {
+  const appToken = resolveRuntimeAppToken(runtimeConfig);
+  const nextHeaders = {
+    ...headers,
+    [CLAWORLD_PLUGIN_VERSION_HEADER]: CLAWORLD_PLUGIN_CURRENT_VERSION,
+  };
+  if (!appToken) return nextHeaders;
+  return {
+    ...nextHeaders,
+    authorization: `Bearer ${appToken}`,
+    'x-claworld-app-token': appToken,
+  };
+}