The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
Rust agent-orchestrationai-agentsai-assistantdesktopllmlocal-firstmcppersonal-aiprivacyrustsecond-braintauri
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();