Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

24.0 KB
Raw Blame
import debug from 'debug';
import { type Socket } from 'socket.io-client';

import { getCoreStateSnapshot } from '../lib/coreState/store';
import { SocketIOMCPTransportImpl } from '../lib/mcp';
import { ingestRuntimeErrorSignal } from '../lib/userErrors/report';
import { store } from '../store';
import { upsertChannelConnection } from '../store/channelConnectionsSlice';
import { setBackend } from '../store/connectivitySlice';
import { resetForUser, setSocketIdForUser, setStatusForUser } from '../store/socketSlice';
import type { ChannelAuthMode, ChannelConnectionStatus, ChannelType } from '../types/channels';
import type { UserErrorScope } from '../types/userError';
import { IS_DEV, IS_TEST } from '../utils/config';
import { createSafeLogData, sanitizeError } from '../utils/sanitize';
import {
  clearCoreRpcTokenCache,
  getCoreRpcToken,
  getCoreRpcUrl,
  resolveCoreSocketEndpoint,
} from './coreRpcClient';
import { createCoreSocket, lastHandshakeToken } from './coreSocket';

// Socket service logger using debug package
// To change these namespaces at runtime, set `localStorage.debug` — NOT the
// DEBUG env var. Under jsdom (and in the browser) the `debug` package resolves
// to its `browser` build, which reads `localStorage.debug` and ignores
// `process.env.DEBUG` entirely, so `DEBUG=socket* pnpm test` silently does
// nothing. The previous comment here claimed otherwise and cost real time.
const socketLog = debug('socket');
const socketWarn = debug('socket:warn');
const socketError = debug('socket:error');

// Enable socket logging in development by default — but never under test.
// `IS_DEV` is truthy in vitest, so without the `IS_TEST` guard this force-enable
// floods every test file that imports this service (measured: 412 lines /
// 46KB of `flow:approval_request` listener churn in a single run), inflating
// runtime enough to push suites past the runner's foreground timeout.
if (IS_DEV && !IS_TEST) {
  debug.enable('socket*');
}

function coreSocketBaseFromRpcUrl(rpcUrl: string): string {
  const trimmed = rpcUrl.trim().replace(/\/+$/, '');
  return trimmed.endsWith('/rpc') ? trimmed.slice(0, -4) : trimmed;
}

/**
 * Resolve the Socket.IO base URL from the user's stored RPC URL preference.
 * Delegates to getCoreRpcUrl() so the stored preference (set on the Welcome
 * screen) is always honoured — previously this called invoke('core_rpc_url')
 * directly, which ignored the user's stored override.
 */
async function resolveCoreSocketBaseUrl(): Promise<string> {
  const rpcUrl = await getCoreRpcUrl();
  return coreSocketBaseFromRpcUrl(rpcUrl);
}

interface ChannelConnectionUpdatedEvent {
  channel: ChannelType;
  authMode: ChannelAuthMode;
  status: ChannelConnectionStatus;
  lastError?: string;
  capabilities?: string[];
}

function normalizeChannelConnectionUpdatePayload(
  value: unknown
): ChannelConnectionUpdatedEvent | null {
  if (!value || typeof value !== 'object') return null;

  const obj = value as Record<string, unknown>;
  const channel = obj.channel;
  const authMode = obj.authMode ?? obj.auth_mode;
  const status = obj.status;
  const lastError = obj.lastError ?? obj.last_error;
  const capabilities = obj.capabilities;

  const isKnownChannel = channel === 'telegram' || channel === 'discord' || channel === 'web';
  const isKnownAuthMode =
    authMode === 'managed_dm' ||
    authMode === 'oauth' ||
    authMode === 'bot_token' ||
    authMode === 'api_key';
  const isKnownStatus =
    status === 'connected' ||
    status === 'connecting' ||
    status === 'disconnected' ||
    status === 'error';

  if (!isKnownChannel || !isKnownAuthMode || !isKnownStatus) {
    return null;
  }

  return {
    channel,
    authMode,
    status,
    lastError: typeof lastError === 'string' ? lastError : undefined,
    capabilities: Array.isArray(capabilities)
      ? capabilities.filter((item): item is string => typeof item === 'string')
      : undefined,
  };
}

function getSocketUserId(): string {
  return getCoreStateSnapshot().snapshot?.auth?.userId ?? '__pending__';
}

class SocketService {
  private socket: Socket | null = null;
  private token: string | null = null;
  private mcpTransport: SocketIOMCPTransportImpl | null = null;
  // Every subscription, as caller callback → wrapped callbacks per event: the
  // registry each new socket is wired from, and how off() finds the exact
  // functions registered with socket.io. Subscriptions outlive any one socket:
  // a reconnect (a new session token, a stale socket) builds a new socket and
  // re-attaches them all, so a subscriber never silently stops hearing events.
  private listenerMap = new Map<
    string,
    Map<(...args: unknown[]) => void, Set<(...args: unknown[]) => void>>
  >();
  // Wrapped callbacks registered through once(), re-attached with once().
  private onceWrapped = new WeakSet<(...args: unknown[]) => void>();

  /**
   * Connect to the socket server with authentication.
   */
  connect(token: string): void {
    void this.connectAsync(token);
  }

  private async connectAsync(token: string): Promise<void> {
    if (!token) return;

    // Don't connect if already connected with the same token
    if (this.socket?.connected && this.token === token) return;

    // Disconnect existing connection if token changed or socket exists
    if (this.socket) {
      if (this.token !== token) {
        this.disconnect();
      } else if (this.socket.connected) {
        return;
      } else if (!this.socket.disconnected) {
        // Socket is connecting, wait for it
        return;
      } else {
        // Stale disconnected socket instance for the same token.
        // Drop it so this connect attempt can create a fresh socket;
        // otherwise the async stale-invocation guard below (`|| this.socket`)
        // returns early and leaves connectivity stuck at "connecting".
        this.socket = null;
        this.mcpTransport = null;
      }
    }

    this.token = token;
    const uid = getSocketUserId();
    store.dispatch(setStatusForUser({ userId: uid, status: 'connecting' }));
    // Mirror backend Socket.IO state into the connectivity channel (#1527).
    store.dispatch(setBackend({ value: 'connecting' }));

    const backendUrl = await resolveCoreSocketBaseUrl();
    // If another `connect(token)` raced in while the URL was resolving,
    // a stale invocation will see `this.token` flipped to the newer JWT
    // (or a fresh socket already attached) and must bail before its
    // io(...) call stomps the newer connection. Same guard repeats
    // after the core-token resolve below.
    if (this.token !== token || this.socket) return;
    socketLog('Connecting to core socket', { userId: uid, backendUrl });

    // Ensure we're not connecting to the wrong URL (Vite dev HMR port guard).
    // Reset the backend channel before returning so it doesn't stay stuck at
    // 'connecting'. (addresses @coderabbitai on socketService.ts:154-163)
    if (backendUrl.includes('localhost:1420') || backendUrl.includes(':1420')) {
      store.dispatch(
        setBackend({ value: 'disconnected', error: 'dev-server URL guard — not a real backend' })
      );
      return;
    }

    // The local core's Socket.IO handshake validates the per-process bearer
    // exposed via `core_rpc_token` (Tauri IPC) / the cloud-mode picker. The
    // session JWT rides alongside on the `auth` payload as `session` so a
    // future handler can correlate the connection with the logged-in user.
    const coreToken = await getCoreRpcToken();
    if (this.token !== token || this.socket) return;

    const endpoint = await resolveCoreSocketEndpoint(backendUrl);
    if (this.token !== token || this.socket) return;
    this.socket = createCoreSocket(endpoint.baseUrl, {
      coreToken,
      authExtras: { session: token },
      // Only a bearer for the core this socket targets: after a gateway
      // switch the fresh bearer belongs to another endpoint, so fall back to
      // this socket's own instead of handing it to the old core.
      resolveToken: async () => {
        const fresh = await getCoreRpcToken();
        // Checked after the read, so a switch during it can't leak the bearer.
        return (await resolveCoreSocketBaseUrl()) === backendUrl ? fresh : null;
      },
      overrides: {
        path: endpoint.path,
        ...(endpoint.transports ? { transports: endpoint.transports } : {}),
        // A remote / tunnelled core (e.g. ~0.8s RTT) needs the socket.io
        // handshake (~2.4s) to outlast the connect timeout — the prior 2s
        // tripped first, flapping the socket and dropping streamed/approval
        // events. 10s gives headroom while still surfacing a genuinely dead
        // core reasonably fast; keep retrying rather than giving up after 5.
        reconnectionDelay: 2000,
        reconnectionAttempts: Infinity,
        timeout: 10000,
        upgrade: true,
        query: {},
      },
    });

    // Wire every subscription onto this socket: those made before any socket
    // existed and those an earlier socket carried before this one replaced it.
    this.attachRegisteredListeners(this.socket);

    this.socket.onAny((event, ...args) => {
      const firstArg = args.length > 0 ? args[0] : undefined;
      socketLog(
        'Inbound event',
        createSafeLogData({ event, argsCount: args.length, hasData: args.length > 0 }, firstArg)
      );
    });

    // Initialize MCP transport for client→server MCP requests
    this.mcpTransport = new SocketIOMCPTransportImpl(this.socket);

    // Connection event handlers
    this.socket.on('connect', () => {
      const socketId = this.socket?.id || null;
      const uid = getSocketUserId();
      socketLog('Connected', { socketId, userId: uid });
      store.dispatch(setStatusForUser({ userId: uid, status: 'connected' }));
      store.dispatch(setSocketIdForUser({ userId: uid, socketId }));
      store.dispatch(setBackend({ value: 'connected' }));

      // Re-join the active thread's room so an in-flight turn's stream survives
      // this (re)connection. Chat events are delivered to both the client_id
      // room and a per-thread room (see socketio.rs `emit_web_channel_event`);
      // because a reconnect produces a NEW client_id, the new socket must
      // re-subscribe to the thread room to keep receiving the stream.
      // With parallel inference several threads may be streaming at once, so
      // re-subscribe to every active thread room (plus the selected thread) —
      // not just a single "active" thread — to keep all in-flight streams alive.
      const threadState = store.getState().thread;
      const roomThreadIds = new Set<string>(Object.keys(threadState?.activeThreadIds ?? {}));
      if (threadState?.selectedThreadId) {
        roomThreadIds.add(threadState.selectedThreadId);
      }
      for (const threadId of roomThreadIds) {
        this.socket?.emit('thread:subscribe', { thread_id: threadId });
      }
    });

    this.socket.on('ready', () => {
      const uid = getSocketUserId();
      socketLog('Server ready - authentication successful', { userId: uid });
    });

    this.socket.on('error', (error: unknown) => {
      const uid = getSocketUserId();
      socketError('Server error', { userId: uid, error: sanitizeError(error) });
    });

    const socket = this.socket;
    this.socket.on('disconnect', (reason: string) => {
      const uid = getSocketUserId();
      socketLog('Disconnected', { userId: uid, reason });
      store.dispatch(setStatusForUser({ userId: uid, status: 'disconnected' }));
      store.dispatch(setSocketIdForUser({ userId: uid, socketId: null }));
      store.dispatch(setBackend({ value: 'disconnected', error: reason }));
      if (reason === 'io server disconnect') void this.retryRejectedHandshake(socket, backendUrl);
    });

    this.socket.on('connect_error', (error: Error) => {
      // The core may have restarted with a new bearer; make the next
      // handshake's `auth` callback re-read it.
      clearCoreRpcTokenCache();
      const uid = getSocketUserId();
      socketError('Connection error', { userId: uid, error: sanitizeError(error) });
      store.dispatch(setStatusForUser({ userId: uid, status: 'disconnected' }));
      store.dispatch(
        setBackend({
          value: 'disconnected',
          error: error instanceof Error ? error.message : String(error),
        })
      );
    });

    const handleChannelConnectionUpdated = (data: unknown) => {
      const payload = normalizeChannelConnectionUpdatePayload(data);
      if (!payload) return;

      store.dispatch(
        upsertChannelConnection({
          channel: payload.channel,
          authMode: payload.authMode,
          patch: {
            status: payload.status,
            lastError: payload.lastError,
            ...(payload.capabilities !== undefined && { capabilities: payload.capabilities }),
          },
        })
      );
    };

    this.socket.on('channel:connection-updated', handleChannelConnectionUpdated);
    this.socket.on('channel_connection_updated', handleChannelConnectionUpdated);

    // Core-side session expiry (401 from the OpenHuman backend or jsonrpc).
    // The server has already published SessionExpired on its event bus,
    // the credentials subscriber has cleared the JWT, and the scheduler
    // gate is flipped to signed-out. All the UI needs to do is mirror
    // that locally and route to onboarding. CoreStateProvider listens
    // for the window event below and calls its own `clearSession`.
    const handleSessionExpired = (data: unknown) => {
      const source =
        (data && typeof data === 'object' && 'source' in data && typeof data.source === 'string'
          ? data.source
          : undefined) ?? 'unknown';
      socketLog('Session expired notification received', { source });
      if (typeof window !== 'undefined') {
        window.dispatchEvent(new CustomEvent('openhuman:session-expired', { detail: { source } }));
      }
    };
    this.socket.on('auth:session_expired', handleSessionExpired);
    this.socket.on('auth_session_expired', handleSessionExpired);

    this.socket.on('memory:sync_stage', (data: unknown) => {
      if (typeof window !== 'undefined') {
        window.dispatchEvent(new CustomEvent('openhuman:memory-sync-stage', { detail: data }));
      }
    });

    this.socket.on('channel:managed-dm-verified', data => {
      const obj = data as Record<string, unknown> | null;
      if (!obj || typeof obj !== 'object') return;
      const token = typeof obj.token === 'string' ? obj.token : undefined;
      const telegramUsername =
        typeof obj.telegramUsername === 'string' ? obj.telegramUsername : undefined;
      const chatId = typeof obj.chatId === 'number' ? obj.chatId : undefined;
      if (!token) return;

      socketLog('Managed DM verified', { tokenLength: token.length, telegramUsername, chatId });
      store.dispatch(
        upsertChannelConnection({
          channel: 'telegram',
          authMode: 'managed_dm',
          patch: { status: 'connected', lastError: undefined, capabilities: ['dm'] },
        })
      );
    });

    // Permanent user-config / billing failures surfaced from background jobs
    // (e.g. cron) — core broadcasts these to the "system" room as a
    // metadata-only `user_error` event carrying a stable kind token in
    // `error_type` (never a raw provider body). Routed through the same
    // classifier the chat runtime uses so the UserErrorCenter renders them
    // durably with a deep-link action, even though no chat thread is active.
    // Producer: core cron scheduler `publish_cron_user_error` (#4165 /
    // TAURI-RUST-HCK follow-up).
    this.socket.on('user_error', (data: unknown) => {
      const obj = data as Record<string, unknown> | null;
      if (!obj) {
        socketWarn('user_error dropped — empty payload');
        return;
      }
      const errorType = typeof obj.error_type === 'string' ? obj.error_type : undefined;
      const provider = typeof obj.error_provider === 'string' ? obj.error_provider : undefined;
      const sourceDomain = typeof obj.error_source === 'string' ? obj.error_source : 'cron';
      socketLog('user_error kind=%s source=%s', errorType ?? 'none', sourceDomain);
      // Scope groups the entry in the panel and is part of its dedupe identity,
      // so it must follow the producing domain. It was pinned to `cron` while
      // the scheduler was the only producer; the memory embedder health gate
      // (#5354) is the second. Unknown domains keep the historical `cron`
      // default rather than widening the scope union from wire data.
      const scope: UserErrorScope = sourceDomain === 'memory' ? 'memory' : 'cron';
      // Metadata-only ingest: forward the stable kind token + scope ONLY, never
      // a raw `message` body. The cron producer already omits it, but we drop
      // any `obj.message` here too so a future/buggy broadcast can't leak raw
      // provider text into the UI — classify() keys on `errorType` for this
      // path. Locks the no-leak contract FE-side (CodeRabbit #4169).
      ingestRuntimeErrorSignal(store.dispatch, { errorType, scope, sourceDomain, provider });
    });

    this.socket.connect();
  }

  /**
   * Disconnect from the socket server
   */
  /**
   * The core refuses a stale bearer by disconnecting the namespace
   * (`io server disconnect`), which socket.io never retries on its own. Re-read
   * the bearer and reconnect — only when it changed, so a bearer the core
   * genuinely rejects does not loop.
   */
  private async retryRejectedHandshake(socket: Socket, backendUrl: string): Promise<void> {
    const used = lastHandshakeToken(socket);
    clearCoreRpcTokenCache();
    const fresh = await getCoreRpcToken();
    // After a gateway switch this socket targets the old core; leave it be.
    const sameCore = (await resolveCoreSocketBaseUrl()) === backendUrl;
    if (this.socket === socket && sameCore && fresh && fresh !== used) {
      socketLog('Core rejected the socket bearer; reconnecting with the refreshed one');
      socket.connect();
    }
  }

  disconnect(): void {
    const uid = getSocketUserId();
    if (this.socket) {
      socketLog('Disconnecting', { userId: uid });
      this.socket.disconnect();
      this.socket = null;
      store.dispatch(resetForUser({ userId: uid }));
    }
    this.token = null;
    this.mcpTransport = null;
    // Subscriptions are kept: the next socket re-attaches them. Subscribers
    // remove their own with off().
  }

  /** Attach every registered subscription to `socket`. */
  private attachRegisteredListeners(socket: Socket): void {
    let count = 0;
    for (const [event, byEvent] of this.listenerMap) {
      for (const wrappedSet of byEvent.values()) {
        for (const wrapped of wrappedSet) {
          if (this.onceWrapped.has(wrapped)) socket.once(event, wrapped);
          else socket.on(event, wrapped);
          count += 1;
        }
      }
    }
    if (count > 0) socketLog('Attached registered listeners', { count });
  }

  /**
   * Get the current socket instance
   */
  getSocket(): Socket | null {
    return this.socket;
  }

  /**
   * Get the MCP transport for making client→server MCP requests
   */
  getMCPTransport(): SocketIOMCPTransportImpl | null {
    return this.mcpTransport;
  }

  /**
   * Check if socket is connected
   */
  isConnected(): boolean {
    return this.socket?.connected || false;
  }

  /**
   * Emit an event to the server
   */
  emit(event: string, data?: unknown): void {
    if (this.socket?.connected) {
      socketLog('Emitting event', createSafeLogData({ event }, data));
      this.socket.emit(event, data);
    } else {
      socketWarn('Cannot emit event - socket not connected', { event });
    }
  }

  /**
   * Join one thread's event room.
   *
   * The reconnect handler re-subscribes from `activeThreadIds`, which the chat
   * runtime clears when the socket drops — so a turn left in flight on a thread
   * the user had navigated away from has no room to be delivered into once a new
   * `client_id` is issued, and its `chat_done` reaches nobody. `ChatRuntimeProvider`
   * calls this for the threads it remembers across that gap (#6034).
   *
   * Emitting the room join directly rather than through {@link emit} keeps a
   * disconnected call quiet: re-subscription is what the `connect` handler
   * already does, so a warning here would only be noise.
   */
  subscribeThread(threadId: string, timeoutMs = 3000): Promise<boolean> {
    if (!threadId || !this.socket?.connected) return Promise.resolve(false);
    socketLog('Subscribing to thread room', { threadId });
    const socket = this.socket;
    return new Promise<boolean>(resolve => {
      let settled = false;
      const finish = (joined: boolean) => {
        if (settled) return;
        settled = true;
        resolve(joined);
      };
      // A caller that reads the thread after this resolves cannot race the
      // join: the server acknowledges only once the socket is in the room.
      // The timeout keeps a server that never acks (an older core) from
      // stalling recovery — the read still happens, just without the ordering
      // guarantee, which is exactly the pre-ack behaviour.
      const timer = setTimeout(() => {
        socketWarn('Thread room subscription not acknowledged', { threadId });
        finish(false);
      }, timeoutMs);
      socket.emit('thread:subscribe', { thread_id: threadId }, () => {
        clearTimeout(timer);
        finish(true);
      });
    });
  }

  /**
   * Listen to an event from the server
   */
  on(event: string, callback: (...args: unknown[]) => void): void {
    const wrappedCallback = (...args: unknown[]) => {
      socketLog('Received event', { event, argsCount: args.length, hasData: args.length > 0 });
      callback(...args);
    };
    // Track original→wrapped per event so the same callback can be used for
    // multiple events without collisions.
    const byEvent = this.listenerMap.get(event) ?? new Map();
    const wrappedSet = byEvent.get(callback) ?? new Set();
    wrappedSet.add(wrappedCallback);
    byEvent.set(callback, wrappedSet);
    this.listenerMap.set(event, byEvent);
    if (this.socket) {
      this.socket.on(event, wrappedCallback);
    } else {
      socketLog('Socket not ready, listener attaches on connect', { event });
    }
  }

  /**
   * Remove an event listener
   */
  off(event: string, callback?: (...args: unknown[]) => void): void {
    if (callback) {
      const byEvent = this.listenerMap.get(event);
      const wrappedSet = byEvent?.get(callback);
      const wrappedCallbacks =
        wrappedSet && wrappedSet.size > 0 ? Array.from(wrappedSet) : [callback];
      const hadWrapped = !!wrappedSet && wrappedSet.size > 0;
      byEvent?.delete(callback);
      if (byEvent && byEvent.size === 0) {
        this.listenerMap.delete(event);
      }
      socketLog('Removing listener', { event, hadWrappedVersion: hadWrapped });
      for (const wrapped of wrappedCallbacks) {
        if (this.socket) {
          this.socket.off(event, wrapped);
        }
      }
    } else {
      socketLog('Removing all listeners for event', { event });
      this.socket?.off(event);
      this.listenerMap.delete(event);
    }
  }

  /**
   * Listen to an event once
   */
  once(event: string, callback: (...args: unknown[]) => void): void {
    const wrappedCallback = (...args: unknown[]) => {
      socketLog('Received event (once)', {
        event,
        argsCount: args.length,
        hasData: args.length > 0,
      });
      try {
        callback(...args);
      } finally {
        const byEvent = this.listenerMap.get(event);
        const wrappedSet = byEvent?.get(callback);
        wrappedSet?.delete(wrappedCallback);
        if (wrappedSet && wrappedSet.size === 0) {
          byEvent?.delete(callback);
        }
        if (byEvent && byEvent.size === 0) {
          this.listenerMap.delete(event);
        }
      }
    };
    const byEvent = this.listenerMap.get(event) ?? new Map();
    const wrappedSet = byEvent.get(callback) ?? new Set();
    wrappedSet.add(wrappedCallback);
    byEvent.set(callback, wrappedSet);
    this.listenerMap.set(event, byEvent);
    this.onceWrapped.add(wrappedCallback);
    if (this.socket) {
      this.socket.once(event, wrappedCallback);
    } else {
      socketLog('Socket not ready, once listener attaches on connect', { event });
    }
  }
}

export const socketService = new SocketService();