@xfxstudio/claworld 0.1.0

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

@@ -0,0 +1,783 @@
+import { EventEmitter } from 'events';
+import WebSocket from 'ws';
+import { resolveClaworldRuntimeConfig } from './config-schema.js';
+import { buildRuntimeAuthHeaders } from './account-identity.js';
+import { createRelayEventProtocol } from '../protocol/relay-event-protocol.js';
+import { createInboundSessionRouter } from '../runtime/inbound-session-router.js';
+import { createOutboundSessionBridge } from '../runtime/outbound-session-bridge.js';
+import {
+  buildPublicErrorPayload,
+  createRuntimeBoundaryError,
+  logRuntimeBoundary,
+} from '../../lib/runtime-errors.js';
+
+const DUPLICATE_CONNECTION_CLOSE_CODE = 4001;
+const STALE_CONNECTION_CLOSE_CODE = 4002;
+const TERMINAL_CLOSE_REASONS = new Set(['duplicate_connection_replaced', 'stale_connection']);
+
+function normalizeRelayWebSocketUrl(serverUrl) {
+  const parsed = new URL(serverUrl);
+  if (parsed.protocol === 'http:') parsed.protocol = 'ws:';
+  if (parsed.protocol === 'https:') parsed.protocol = 'wss:';
+
+  const pathname = parsed.pathname || '/';
+  const normalizedPathname = pathname.replace(/\/+$/, '') || '/';
+  parsed.pathname = normalizedPathname === '/' || normalizedPathname === ''
+    ? '/ws'
+    : normalizedPathname.endsWith('/ws')
+      ? normalizedPathname
+      : normalizedPathname + '/ws';
+
+  return parsed.toString();
+}
+
+function buildInboundEnvelope(message = {}) {
+  const data = message.data || {};
+  const sessionId = data.sessionId || data.requestId || null;
+  const eventId = data.turnId || data.requestId || data.sessionId || null;
+
+  switch (message.event) {
+    case 'request.received':
+      return {
+        session_id: sessionId,
+        event_id: eventId,
+        from_agent_id: data.fromAgentId || data.fromAgent?.agentId || null,
+        type: 'system_message',
+        payload: { kind: 'request.received', ...data },
+      };
+    case 'session.created':
+      return {
+        session_id: sessionId,
+        event_id: eventId,
+        from_agent_id: data.fromAgentId || data.targetAgentId || null,
+        type: 'system_message',
+        payload: { kind: 'session.created', ...data },
+      };
+    case 'turn.deliver':
+      return {
+        session_id: sessionId,
+        event_id: eventId,
+        from_agent_id: data.fromAgentId || data.fromAgent?.agentId || null,
+        type: 'message',
+        payload: data.payload || {},
+      };
+    case 'turn.reply':
+      return {
+        session_id: sessionId,
+        event_id: eventId,
+        from_agent_id: data.fromAgentId || data.fromAgent?.agentId || null,
+        type: 'message',
+        payload: data.payload || {},
+      };
+    case 'turn.timeout':
+      return {
+        session_id: sessionId,
+        event_id: eventId,
+        from_agent_id: data.fromAgentId || null,
+        type: 'system_message',
+        payload: { kind: 'turn.timeout', ...data },
+      };
+    case 'session.terminated':
+      return {
+        session_id: sessionId,
+        event_id: eventId,
+        from_agent_id: data.actorAgentId || null,
+        type: 'session_end',
+        payload: { kind: 'session.terminated', ...data },
+      };
+    default:
+      return null;
+  }
+}
+
+export class ClaworldRelayClient extends EventEmitter {
+  constructor({
+    logger = console,
+    inbound = createInboundSessionRouter(),
+    outbound = createOutboundSessionBridge(),
+    protocol = createRelayEventProtocol(),
+    wsFactory = (url) => new WebSocket(url),
+    httpFetch = globalThis.fetch,
+  } = {}) {
+    super();
+    this.logger = logger;
+    this.inbound = inbound;
+    this.outbound = outbound;
+    this.protocol = protocol;
+    this.wsFactory = wsFactory;
+    this.httpFetch = httpFetch;
+    this.ws = null;
+    this.events = [];
+    this.heartbeatTimer = null;
+    this.connectionState = 'idle';
+    this.runtimeConfig = null;
+    this.boundAgentId = null;
+    this.serverUrl = null;
+    this.connectionParams = null;
+    this.reconnectTimer = null;
+    this.reconnectAttempts = 0;
+    this.manualClose = false;
+    this.lastDisconnectInfo = null;
+  }
+
+  buildBoundaryContext(extra = null) {
+    return {
+      accountId: this.runtimeConfig?.accountId || null,
+      agentId: this.boundAgentId,
+      ...(extra && typeof extra === 'object' ? extra : {}),
+    };
+  }
+
+  buildDisconnectInfo(code = null, reason = null, source = 'socket') {
+    const reasonText = String(reason || '').trim() || null;
+    return {
+      code: Number.isInteger(code) ? code : null,
+      reason: reasonText,
+      source,
+      recoverable: !(
+        code === DUPLICATE_CONNECTION_CLOSE_CODE
+        || code === STALE_CONNECTION_CLOSE_CODE
+        || TERMINAL_CLOSE_REASONS.has(reasonText)
+      ),
+    };
+  }
+
+  clearReconnectTimer() {
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = null;
+  }
+
+  resolveReconnectDelayMs() {
+    const heartbeatSeconds = Number(this.runtimeConfig?.heartbeatSeconds || 1);
+    return Math.min(5000, Math.max(500, Math.floor(heartbeatSeconds * 500)));
+  }
+
+  shouldAutoReconnect(disconnectInfo = null) {
+    if (this.manualClose) return false;
+    if (this.runtimeConfig?.reconnect === false) return false;
+    return disconnectInfo?.recoverable !== false;
+  }
+
+  emitRelayMessage(message, { sessionTarget, fallbackTarget }) {
+    this.events.push(message);
+    this.emit('event', message);
+    if (message.event === 'error') {
+      this.emit('relay_error', message);
+      this.emit('relay.error', message);
+    } else {
+      this.emit(message.event, message);
+    }
+
+    const inboundEnvelope = buildInboundEnvelope(message);
+    if (!inboundEnvelope) return;
+    const described = this.protocol.describeEvent(inboundEnvelope);
+    const route = this.inbound.routeInboundEvent(inboundEnvelope, {
+      sessionTarget: sessionTarget || this.runtimeConfig.routing.sessionTarget,
+      fallbackTarget: fallbackTarget || this.runtimeConfig.routing.fallbackTarget,
+    });
+    const runtimeEvent = {
+      relayEvent: message.event,
+      protocol: described,
+      inboundEnvelope,
+      route,
+      raw: message,
+    };
+    this.emit('runtime_event', runtimeEvent);
+  }
+
+  emitBoundaryError(
+    label,
+    error,
+    {
+      code = 'relay_runtime_error',
+      category = 'runtime',
+      publicMessage = 'relay runtime error',
+      recoverable = true,
+      context = null,
+      errorType = 'relay_runtime_error',
+      fallbackMessage = null,
+      includeStack = false,
+    } = {},
+  ) {
+    const normalized = logRuntimeBoundary(this.logger, label, error, this.buildBoundaryContext(context), {
+      includeStack,
+      fallback: {
+        code,
+        category,
+        publicMessage,
+        recoverable,
+      },
+    });
+    const payload = {
+      event: 'error',
+      data: buildPublicErrorPayload(normalized, {
+        errorType,
+        fallbackMessage: fallbackMessage || publicMessage,
+        exposeMessage: true,
+      }),
+    };
+    this.events.push(payload);
+    this.emit('event', payload);
+    this.emit('relay_error', payload);
+    this.emit('relay.error', payload);
+    return normalized;
+  }
+
+  buildDisconnectInfoFromError(error, source = 'reconnect') {
+    if (error?.close) return error.close;
+    return this.buildDisconnectInfo(null, error?.reason || error?.code || error?.message || 'reconnect_failed', source);
+  }
+
+  createClosedBeforeAuthError(disconnectInfo, cause = null) {
+    const normalized = createRuntimeBoundaryError({
+      code: 'relay_ws_closed_before_auth',
+      category: 'transport',
+      status: 502,
+      message: `relay websocket closed before authentication (code=${disconnectInfo?.code ?? 'unknown'}, reason=${disconnectInfo?.reason || ''})`,
+      publicMessage: 'relay websocket closed before authentication',
+      recoverable: disconnectInfo?.recoverable !== false,
+      context: this.buildBoundaryContext({
+        stage: 'pre_auth_close',
+        closeCode: disconnectInfo?.code ?? null,
+        closeReason: disconnectInfo?.reason || null,
+      }),
+      cause,
+    });
+    normalized.reason = disconnectInfo?.reason || normalized.code;
+    normalized.close = disconnectInfo;
+    normalized.fatal = disconnectInfo?.recoverable === false;
+    return normalized;
+  }
+
+  async requestJson(pathName, init = {}, fallback = {}) {
+    if (!this.serverUrl) {
+      throw createRuntimeBoundaryError({
+        code: 'relay_client_not_connected',
+        category: 'runtime',
+        status: 409,
+        message: 'client not connected',
+        publicMessage: 'relay client is not connected',
+        recoverable: true,
+      });
+    }
+
+    const url = `${this.serverUrl}${pathName}`;
+    let response;
+    try {
+      response = await this.httpFetch(url, init);
+    } catch (error) {
+      throw createRuntimeBoundaryError({
+        code: fallback.code || 'relay_fetch_failed',
+        category: 'transport',
+        status: 502,
+        message: `${fallback.message || 'relay request failed'}: ${error?.message || String(error)}`,
+        publicMessage: fallback.publicMessage || 'relay request failed',
+        recoverable: true,
+        context: {
+          url,
+          method: init?.method || 'GET',
+        },
+        cause: error,
+      });
+    }
+
+    let body = null;
+    try {
+      body = await response.json();
+    } catch (error) {
+      throw createRuntimeBoundaryError({
+        code: 'relay_response_invalid',
+        category: 'transport',
+        status: 502,
+        message: `relay response was not valid JSON: ${error?.message || String(error)}`,
+        publicMessage: 'relay response was not valid JSON',
+        recoverable: true,
+        context: {
+          url,
+          method: init?.method || 'GET',
+          status: response.status,
+        },
+        cause: error,
+      });
+    }
+
+    return { status: response.status, body };
+  }
+
+  async openSocket({
+    wsUrl,
+    agentId,
+    credential,
+    clientVersion,
+    sessionTarget,
+    fallbackTarget,
+  }) {
+    this.connectionState = this.connectionState === 'reconnecting' ? 'reconnecting' : 'connecting';
+
+    return await new Promise((resolve, reject) => {
+      let settled = false;
+      let suppressCloseHandler = false;
+      const ws = this.wsFactory(wsUrl);
+      this.ws = ws;
+
+      ws.on('open', () => {
+        this.logger.info?.('[claworld:relay-client] websocket open, sending auth', {
+          accountId: this.runtimeConfig.accountId,
+          agentId,
+          clientVersion,
+        });
+        this.send({
+          type: 'auth',
+          agentId,
+          credential,
+          clientVersion,
+        });
+      });
+
+      ws.on('message', (buf) => {
+        let message;
+        try {
+          message = JSON.parse(String(buf));
+        } catch (error) {
+          const normalized = this.emitBoundaryError('[claworld:relay-client] invalid relay message', error, {
+            code: 'relay_ws_message_invalid',
+            category: 'transport',
+            publicMessage: 'relay websocket delivered invalid JSON',
+            context: { stage: 'message_parse' },
+          });
+          if (!settled) {
+            settled = true;
+            this.connectionState = 'error';
+            reject(normalized);
+          }
+          return;
+        }
+
+        try {
+          this.emitRelayMessage(message, { sessionTarget, fallbackTarget });
+
+          if (message.event === 'auth.ok' && !settled) {
+            settled = true;
+            this.connectionState = 'authenticated';
+            this.reconnectAttempts = 0;
+            this.logger.info?.('[claworld:relay-client] auth ok', {
+              accountId: this.runtimeConfig.accountId,
+              agentId,
+            });
+            this.startHeartbeatLoop();
+            resolve(message);
+          }
+
+          if (message.event === 'error' && !settled && message.data?.code === 'unauthorized') {
+            settled = true;
+            suppressCloseHandler = true;
+            this.connectionState = 'error';
+            const authReason = message.data?.reason || message.data?.error || 'unauthorized';
+            const authError = createRuntimeBoundaryError({
+              code: message.data?.code || 'unauthorized',
+              category: 'auth',
+              status: 401,
+              message: authReason,
+              publicMessage: 'relay authentication failed',
+              recoverable: true,
+              context: this.buildBoundaryContext({
+                stage: 'auth',
+                reason: authReason,
+              }),
+            });
+            authError.reason = authReason;
+            authError.fatal = true;
+            authError.close = this.buildDisconnectInfo(null, authReason, 'auth');
+            this.logger.error?.('[claworld:relay-client] auth failed', {
+              accountId: this.runtimeConfig.accountId,
+              agentId,
+              error: authError.message,
+              code: authError.code,
+            });
+            reject(authError);
+          }
+        } catch (error) {
+          const normalized = this.emitBoundaryError('[claworld:relay-client] relay message handling failed', error, {
+            code: 'relay_ws_message_handling_failed',
+            category: 'runtime',
+            publicMessage: 'relay websocket message handling failed',
+            context: {
+              stage: 'message_handle',
+              relayEvent: message?.event || null,
+            },
+          });
+          if (!settled) {
+            settled = true;
+            suppressCloseHandler = true;
+            this.connectionState = 'error';
+            reject(normalized);
+          }
+        }
+      });
+
+      ws.on('close', (code, reason) => {
+        if (this.ws === ws) this.ws = null;
+        this.stopHeartbeatLoop();
+        const disconnectInfo = this.buildDisconnectInfo(code, reason);
+        this.lastDisconnectInfo = disconnectInfo;
+        this.logger.warn?.('[claworld:relay-client] websocket closed', {
+          accountId: this.runtimeConfig?.accountId || null,
+          agentId: this.boundAgentId,
+          code: disconnectInfo.code,
+          reason: disconnectInfo.reason || '',
+          recoverable: disconnectInfo.recoverable,
+        });
+        this.emit('disconnect', disconnectInfo);
+        if (suppressCloseHandler) return;
+
+        if (!settled) {
+          settled = true;
+          this.connectionState = disconnectInfo.reason === 'duplicate_connection_replaced' ? 'replaced' : 'error';
+          reject(this.createClosedBeforeAuthError(disconnectInfo));
+          return;
+        }
+
+        if (this.shouldAutoReconnect(disconnectInfo)) {
+          this.connectionState = 'reconnecting';
+          this.scheduleReconnect(disconnectInfo);
+          return;
+        }
+
+        this.connectionState = disconnectInfo.reason === 'duplicate_connection_replaced' ? 'replaced' : 'closed';
+        this.emit('close', disconnectInfo);
+      });
+
+      ws.on('error', (error) => {
+        const normalized = logRuntimeBoundary(this.logger, '[claworld:relay-client] websocket error', error, this.buildBoundaryContext({
+          stage: settled ? 'runtime_socket_error' : 'connect_socket_error',
+        }), {
+          includeStack: false,
+          fallback: {
+            code: settled ? 'relay_ws_runtime_error' : 'relay_ws_connect_failed',
+            category: 'transport',
+            publicMessage: settled ? 'relay websocket runtime error' : 'relay websocket connection failed',
+            recoverable: true,
+          },
+        });
+        if (!settled) {
+          settled = true;
+          suppressCloseHandler = true;
+          this.connectionState = 'error';
+          normalized.reason = normalized.reason || normalized.code || normalized.message;
+          reject(normalized);
+        }
+      });
+    });
+  }
+
+  scheduleReconnect(disconnectInfo = null) {
+    if (!this.shouldAutoReconnect(disconnectInfo)) {
+      this.connectionState = 'closed';
+      this.emit('close', disconnectInfo || this.buildDisconnectInfo(null, 'reconnect_disabled', 'reconnect'));
+      return;
+    }
+
+    this.clearReconnectTimer();
+    const delayMs = this.resolveReconnectDelayMs();
+    const attempt = this.reconnectAttempts + 1;
+    this.reconnectAttempts = attempt;
+    this.logger.warn?.('[claworld:relay-client] scheduling reconnect', {
+      accountId: this.runtimeConfig?.accountId || null,
+      agentId: this.boundAgentId,
+      attempt,
+      delayMs,
+      reason: disconnectInfo?.reason || null,
+    });
+    this.emit('reconnecting', { attempt, delayMs, disconnectInfo });
+
+    this.reconnectTimer = setTimeout(async () => {
+      this.reconnectTimer = null;
+      if (this.manualClose || !this.connectionParams) return;
+
+      try {
+        await this.openSocket(this.connectionParams);
+        this.emit('reconnected', { attempt, disconnectInfo });
+      } catch (error) {
+        const nextDisconnect = this.buildDisconnectInfoFromError(error);
+        this.lastDisconnectInfo = nextDisconnect;
+        if (error?.fatal || !this.shouldAutoReconnect(nextDisconnect)) {
+          this.connectionState = nextDisconnect.reason === 'duplicate_connection_replaced' ? 'replaced' : 'error';
+          this.emit('close', nextDisconnect);
+          return;
+        }
+        this.connectionState = 'reconnecting';
+        this.scheduleReconnect(nextDisconnect);
+      }
+    }, delayMs);
+
+    if (typeof this.reconnectTimer.unref === 'function') this.reconnectTimer.unref();
+  }
+
+  async connect({
+    config,
+    agentId,
+    credential = null,
+    clientVersion = 'claworld-plugin/0.1.0',
+    sessionTarget,
+    fallbackTarget,
+  } = {}) {
+    if (!agentId) {
+      throw createRuntimeBoundaryError({
+        code: 'relay_agent_id_required',
+        category: 'input',
+        status: 400,
+        message: 'agentId is required',
+        publicMessage: 'agentId is required',
+        recoverable: true,
+      });
+    }
+
+    this.runtimeConfig = resolveClaworldRuntimeConfig(config);
+    this.boundAgentId = agentId;
+    this.serverUrl = this.runtimeConfig.serverUrl;
+    this.manualClose = false;
+    this.clearReconnectTimer();
+
+    const wsUrl = normalizeRelayWebSocketUrl(this.runtimeConfig.serverUrl);
+    this.connectionParams = {
+      wsUrl,
+      agentId,
+      credential,
+      clientVersion,
+      sessionTarget,
+      fallbackTarget,
+    };
+    this.connectionState = 'connecting';
+
+    this.logger.info?.('[claworld:relay-client] connecting websocket', {
+      accountId: this.runtimeConfig.accountId,
+      agentId,
+      wsUrl,
+      reconnect: this.runtimeConfig.reconnect !== false,
+    });
+
+    return await this.openSocket(this.connectionParams);
+  }
+
+  startHeartbeatLoop() {
+    this.stopHeartbeatLoop();
+    const intervalMs = this.runtimeConfig.heartbeatSeconds * 1000;
+    this.heartbeatTimer = setInterval(() => {
+      try {
+        this.sendHeartbeat();
+      } catch (error) {
+        logRuntimeBoundary(this.logger, '[claworld:relay-client] heartbeat failed', error, this.buildBoundaryContext({
+          stage: 'heartbeat',
+        }), {
+          includeStack: false,
+          fallback: {
+            code: 'relay_heartbeat_failed',
+            category: 'transport',
+            publicMessage: 'relay heartbeat failed',
+            recoverable: true,
+          },
+        });
+      }
+    }, intervalMs);
+    if (typeof this.heartbeatTimer.unref === 'function') this.heartbeatTimer.unref();
+  }
+
+  stopHeartbeatLoop() {
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+    this.heartbeatTimer = null;
+  }
+
+  send(payload) {
+    if (!this.ws || this.ws.readyState !== 1) {
+      throw createRuntimeBoundaryError({
+        code: 'relay_ws_not_connected',
+        category: 'transport',
+        status: 409,
+        message: 'relay websocket is not connected',
+        publicMessage: 'relay websocket is not connected',
+        recoverable: true,
+        context: this.buildBoundaryContext({
+          stage: 'send',
+        }),
+      });
+    }
+    this.ws.send(JSON.stringify(payload));
+  }
+
+  sendHeartbeat() {
+    this.send({ type: 'heartbeat' });
+  }
+
+  sendTurnReply({ sessionId, messageId = null, replyText, source = 'subagent', control = null } = {}) {
+    const envelope = this.outbound.createReplyEnvelope({ sessionId, messageId, replyText, source, control });
+    this.send({
+      type: 'turn.reply',
+      sessionId,
+      payload: {
+        text: envelope.reply_text,
+        source: envelope.source,
+        trace: envelope.trace,
+        ...(envelope.control ? { control: envelope.control } : {}),
+      },
+    });
+    return envelope;
+  }
+
+  terminateSession({ sessionId, reason = 'client_terminate' } = {}) {
+    this.send({ type: 'session.terminate', sessionId, reason });
+  }
+
+  async createSessionRequest({ fromAgentId, toAddress, requestContext = {} } = {}) {
+    return await this.requestJson('/v1/session-requests', {
+      method: 'POST',
+      headers: buildRuntimeAuthHeaders(this.runtimeConfig, { 'content-type': 'application/json' }),
+      body: JSON.stringify({ fromAgentId, toAddress, requestContext }),
+    }, {
+      code: 'relay_request_create_failed',
+      message: 'failed to create relay session request',
+      publicMessage: 'failed to create relay session request',
+    });
+  }
+
+  async acceptSessionRequest(requestId, { actorAgentId, ...options } = {}) {
+    return await this.requestJson(`/v1/session-requests/${requestId}/accept`, {
+      method: 'POST',
+      headers: buildRuntimeAuthHeaders(this.runtimeConfig, { 'content-type': 'application/json' }),
+      body: JSON.stringify({ actorAgentId, ...options }),
+    }, {
+      code: 'relay_request_accept_failed',
+      message: 'failed to accept relay session request',
+      publicMessage: 'failed to accept relay session request',
+    });
+  }
+
+  async deliverMessage({ fromAgentId, toAddress, payload = {}, conversation = {} } = {}) {
+    return await this.requestJson('/v1/messages', {
+      method: 'POST',
+      headers: buildRuntimeAuthHeaders(this.runtimeConfig, { 'content-type': 'application/json' }),
+      body: JSON.stringify({ fromAgentId, toAddress, payload, conversation }),
+    }, {
+      code: 'relay_message_delivery_failed',
+      message: 'failed to deliver relay message',
+      publicMessage: 'failed to deliver relay message',
+    });
+  }
+
+  async createTurn({ sessionId, fromAgentId, payload = {} } = {}) {
+    return await this.requestJson(`/v1/sessions/${sessionId}/turns`, {
+      method: 'POST',
+      headers: buildRuntimeAuthHeaders(this.runtimeConfig, { 'content-type': 'application/json' }),
+      body: JSON.stringify({ fromAgentId, payload }),
+    }, {
+      code: 'relay_turn_create_failed',
+      message: 'failed to create relay turn',
+      publicMessage: 'failed to create relay turn',
+    });
+  }
+
+  waitFor(eventNameOrPredicate, timeoutMs = 8000) {
+    const isPredicate = typeof eventNameOrPredicate === 'function';
+    const predicate = isPredicate
+      ? eventNameOrPredicate
+      : (event) => event.event === eventNameOrPredicate;
+
+    return new Promise((resolve, reject) => {
+      const existing = this.events.find(predicate);
+      if (existing) return resolve(existing);
+
+      const started = Date.now();
+      const timer = setInterval(() => {
+        const found = this.events.find(predicate);
+        if (found) {
+          clearInterval(timer);
+          resolve(found);
+        } else if (Date.now() - started > timeoutMs) {
+          clearInterval(timer);
+          const eventName = isPredicate ? 'predicate event' : eventNameOrPredicate;
+          reject(new Error(`timed out waiting for ${eventName}`));
+        }
+      }, 100);
+    });
+  }
+
+  async establishSession({ fromAgentId, toAddress, requestContext = {}, openingPayload = {} } = {}) {
+    const normalizedRequestContext = requestContext && typeof requestContext === 'object' && !Array.isArray(requestContext)
+      ? { ...requestContext }
+      : {};
+    const normalizedOpeningPayload = openingPayload && typeof openingPayload === 'object' && !Array.isArray(openingPayload)
+      ? { ...openingPayload }
+      : {};
+    if (Object.keys(normalizedOpeningPayload).length > 0) {
+      normalizedRequestContext.openingPayload = normalizedOpeningPayload;
+      if (!normalizedRequestContext.message && typeof normalizedOpeningPayload.text === 'string' && normalizedOpeningPayload.text.trim()) {
+        normalizedRequestContext.message = normalizedOpeningPayload.text.trim();
+      }
+    }
+
+    const requestResult = await this.createSessionRequest({
+      fromAgentId,
+      toAddress,
+      requestContext: normalizedRequestContext,
+    });
+    if (requestResult.status !== 201) {
+      throw new Error(`failed to create session request: ${JSON.stringify(requestResult.body)}`);
+    }
+    const requestId = requestResult.body.requestId;
+    return {
+      requestId,
+      sessionId: null,
+      openApprovedSession: async ({ timeoutMs = 15000 } = {}) => {
+        const acceptedEvent = await this.waitFor(
+          (event) => event.event === 'request.updated'
+            && event.data?.requestId === requestId
+            && event.data?.status === 'accepted',
+          timeoutMs,
+        );
+        const kickoff = acceptedEvent?.data?.kickoff && typeof acceptedEvent.data.kickoff === 'object'
+          ? acceptedEvent.data.kickoff
+          : null;
+        return {
+          requestId,
+          sessionId: kickoff?.sessionId || null,
+          kickoff,
+        };
+      },
+    };
+  }
+
+  snapshot() {
+    return {
+      connectionState: this.connectionState,
+      boundAgentId: this.boundAgentId,
+      eventCount: this.events.length,
+      heartbeatSeconds: this.runtimeConfig?.heartbeatSeconds || null,
+      hasActiveSocket: Boolean(this.ws && this.ws.readyState === 1),
+      reconnectEnabled: this.runtimeConfig?.reconnect !== false,
+      reconnectAttempts: this.reconnectAttempts,
+      lastDisconnectCode: this.lastDisconnectInfo?.code ?? null,
+      lastDisconnectReason: this.lastDisconnectInfo?.reason || null,
+    };
+  }
+
+  async close(reason = 'manual_close') {
+    this.manualClose = true;
+    this.clearReconnectTimer();
+    this.stopHeartbeatLoop();
+    if (!this.ws) return { closed: false, reason: 'not_connected' };
+    const ws = this.ws;
+    this.ws = null;
+    await new Promise((resolve) => {
+      if (ws.readyState === 3) return resolve();
+      ws.once('close', resolve);
+      ws.close(1000, reason);
+    });
+    this.connectionState = 'closed';
+    return { closed: true, reason };
+  }
+}
+
+export function createClaworldRelayClient(options = {}) {
+  return new ClaworldRelayClient(options);
+}
+
+export { normalizeRelayWebSocketUrl };