import type { WSContext } from 'hono/ws' import { getEventBus } from './event-bus' import type { SessionEvent } from './event-bus' import { publishSessionEvent } from '../services/transport' import { getSession, updateSessionStatus } from '../services/session' import { handleTitleControlResponse, maybeRequestSessionTitle, } from '../services/session-titles' import { clearPendingPermissions, getPendingPermissionCount, registerPendingPermission, resolvePendingPermission, } from '../services/pending-permissions' import { log, error as logError } from '../logger' import { toClientPayload } from './client-payload' import { wipeSessionConversation } from '../services/session-clear' import { redispatchWorkForSession } from '../services/work-dispatch' import { config } from '../config' // Per-connection cleanup, keyed by sessionId (only one WS per session) interface CleanupEntry { unsub: () => void keepalive: ReturnType ws: WSContext openTime: number lastClientActivity: number } const cleanupBySession = new Map() // Track all active WS connections for graceful shutdown const activeConnections = new Set() /** * Event types excluded from the WS-reconnect history replay. These are * point-in-time RPC traffic, not conversation state: replaying them to the * bridge would re-execute them as fresh requests — a replayed `interrupt` * aborts whatever turn is running AFTER the reconnect, replayed * `get_context_usage` fires spurious responses, and replayed * permission asks/responses resurrect stale dialogs. The replay exists so * the bridge can reconstruct the conversation transcript (user/assistant/ * system messages) — control traffic has no reconstruction value. */ const NON_REPLAYABLE_EVENT_TYPES = new Set([ 'control_request', 'control_response', 'control_cancel_request', 'permission_request', 'permission_response', 'interrupt', ]) /** * Exception to NON_REPLAYABLE_EVENT_TYPES: outbound control/permission * RESPONSES (Web-UI approvals, denials, generic control answers) are * replay-safe and MUST be re-delivered on reconnect. * * The live subscriber silently drops every outbound event published while * ws.readyState !== 1 (the reconnect window). For conversation events the * replay below covers that; for approval responses it used not to — they * were in NON_REPLAYABLE_EVENT_TYPES, so an approval sent during the gap * was lost forever. The worker's turn then stayed parked on the permission * wait (no timeout on the pending handler), the session sat on * requires_action with the card already optimistically removed → total * deadlock (observed: `slz rcs one` stuck mid-task at a permission step). * * Replay safety: the worker settles responses by request_id — a response * for an already-settled/unknown request is logged and ignored * (useReplBridge handlePermissionResponse). Inbound (worker-authored) * responses are NOT covered by this exception — they stay filtered. * Outbound control_REQUESTS (interrupt, set_model, RPCs) stay * non-replayable: a replayed interrupt would abort the post-reconnect * turn. */ function isReplayableOutboundResponse(event: SessionEvent): boolean { if (event.direction !== 'outbound') return false return ( event.type === 'control_response' || event.type === 'permission_response' ) } // Server-side keepalive interval (configurable via RCS_WS_KEEPALIVE_INTERVAL). // Sends data frames to keep reverse proxies from closing idle connections. const SERVER_KEEPALIVE_INTERVAL_MS = (config.wsKeepaliveInterval || 20) * 1000 // If no client data received within this threshold, the connection is // considered dead. Configurable via RCS_WS_CLIENT_INACTIVITY_TIMEOUT (seconds) // and defaulting to 300s so it comfortably exceeds the bridge child's // session_keepalive_interval_v2_ms (default 120s) — otherwise healthy idle // sessions get torn down between client keepalives. const CLIENT_ACTIVITY_TIMEOUT_MS = (config.wsClientInactivityTimeout || 300) * 1000 /** * Worker 回执销账后,会话已不再阻塞在审批上 — 把派生状态从 * requires_action 落回 running。V1 REPL 的 reportState 是 no-op,若只等 * 后续 assistant 事件,Dashboard/会话行会在工具执行期间继续显示「需要 * 操作」。`turnActive` 保证只在回合内生效;回合结束的 result 会再落 idle。 */ export function settlePermissionStatus(sessionId: string): void { if (getPendingPermissionCount(sessionId) > 0) return const session = getSession(sessionId) if (session?.status !== 'requires_action') return if (!getEventBus(sessionId).turnActive) return updateSessionStatus(sessionId, 'running') } /** * Convert internal EventBus event -> SDK message for bridge client. */ function toSDKMessage(event: SessionEvent): string { // NDJSON format: each message MUST end with \n so the child process's // line-based parser can split messages correctly. return JSON.stringify(toClientPayload(event)) + '\n' } /** Called from onOpen — subscribes to event bus, forwards outbound events to bridge WS */ export function handleWebSocketOpen(ws: WSContext, sessionId: string) { const openTime = Date.now() const lastClientActivity = Date.now() log(`[RC-DEBUG] [WS] Open session=${sessionId}`) activeConnections.add(ws) // If there's an existing connection for this session, clean it up first const existing = cleanupBySession.get(sessionId) if (existing) { log(`[WS] Replacing existing connection for session=${sessionId}`) existing.unsub() clearInterval(existing.keepalive) activeConnections.delete(existing.ws) } const bus = getEventBus(sessionId) // Replay conversation events so the bridge can reconstruct the full // history — assistant replies are inbound events. Transient streaming // deltas are skipped (display-only, would flood the child's stdin parser), // and so is point-in-time control traffic (see NON_REPLAYABLE_EVENT_TYPES — // a replayed interrupt would abort the post-reconnect turn). Outbound // approval/permission RESPONSES are the exception — see // isReplayableOutboundResponse. const missed = bus.getEventsSince(0) if (missed.length > 0) { const replayable = missed.filter( event => !NON_REPLAYABLE_EVENT_TYPES.has(event.type) || isReplayableOutboundResponse(event), ) log( `[WS] Replaying ${replayable.length} of ${missed.length} retained event(s)`, ) for (const event of replayable) { if (ws.readyState !== 1) break if (event.type === 'stream_event' || event.type === 'partial_assistant') continue try { ws.send(toSDKMessage(event)) } catch { // ignore send errors during replay } } } const unsub = bus.subscribe((event: SessionEvent) => { if (ws.readyState !== 1) return if (event.direction !== 'outbound') return try { const sdkMsg = toSDKMessage(event) log( `[RC-DEBUG] [WS] -> bridge (outbound): type=${event.type} len=${sdkMsg.length} msg=${sdkMsg.slice(0, 300)}`, ) ws.send(sdkMsg) } catch (err) { logError('[RC-DEBUG] [WS] send error:', err) } }) const keepalive = setInterval(() => { if (ws.readyState !== 1) { clearInterval(keepalive) return } // Check if client is still alive — close if no data received for too // long (see closeInactiveClient: the close doubles as the write-path // recovery trigger via work re-dispatch). if (closeInactiveClient(sessionId)) { return } try { ws.send('{"type":"keep_alive"}\n') } catch { clearInterval(keepalive) } }, SERVER_KEEPALIVE_INTERVAL_MS) cleanupBySession.set(sessionId, { unsub, keepalive, ws, openTime, lastClientActivity, }) } /** * Called from onMessage — bridge sends newline-delimited JSON. * * Activity tracking skips pure keep_alive frames: with HybridTransport the * worker's WS-layer keepalives (WebSocketTransport.startKeepaliveInterval, * direct socket writes) keep flowing even when the POST write path is dead — * counting them would make the inactivity close (and its write-path * recovery re-dispatch) unreachable for exactly the zombie state it exists * to detect. Real WS messages and ALL POST ingress still refresh the clock. */ export function handleWebSocketMessage( ws: WSContext, sessionId: string, data: string, ) { const lines = data.split('\n').filter(l => l.trim()) for (const line of lines) { try { const parsed = JSON.parse(line) as Record // Track client activity for dead-connection detection — non-keepalive // frames only (see function comment). if (parsed.type !== 'keep_alive') { touchClientActivity(sessionId) } ingestBridgeMessage(sessionId, parsed) } catch (err) { logError('[WS] parse error:', err) } } } /** * Mark the session's WS connection as recently active. Called from both the * WS onMessage path and the HTTP POST session-ingress path — HybridTransport * children send events via POST (not WS), so without touching here the server * would close the WS as dead even though the child is actively POSTing. */ export function touchClientActivity(sessionId: string): void { const entry = cleanupBySession.get(sessionId) if (entry) { entry.lastClientActivity = Date.now() } } /** * Inactivity sweep for one session's WS connection. Returns true when the * connection was closed as dead. * * With HybridTransport the inactivity clock ONLY advances via HTTP POST * ingress (writes go through POST; the WS carries no app-level * client→server frames). 300s of silence with a live WS therefore means the * worker's event uploader is wedged, not that the WS is dead — the WS will * auto-reconnect within seconds. Closing it alone changes nothing (the * zombie uploader is per-transport and survives WS reconnects), so this * also queues a recovery work item: the worker's next at-capacity poll * (≤10 min) fires onWorkReceived → fresh transport (fresh uploader) → the * write path recovers. See redispatchWorkForSession. */ export function closeInactiveClient( sessionId: string, now: number = Date.now(), ): boolean { const entry = cleanupBySession.get(sessionId) if (!entry) return false if (entry.ws.readyState !== 1) return false const silenceMs = now - entry.lastClientActivity if (silenceMs <= CLIENT_ACTIVITY_TIMEOUT_MS) return false log( `[WS] Client inactive for ${Math.round(silenceMs / 1000)}s on session=${sessionId}, closing dead connection`, ) try { entry.ws.close(1000, 'client inactive') } catch { // already closed } void redispatchWorkForSession(sessionId) return true } /** Called from onClose — unsubscribes from event bus */ export function handleWebSocketClose( ws: WSContext, sessionId: string, code?: number, reason?: string, ) { activeConnections.delete(ws) const entry = cleanupBySession.get(sessionId) const duration = entry ? Math.round((Date.now() - entry.openTime) / 1000) : -1 log( `[WS] Close session=${sessionId} code=${code ?? 'none'} reason=${reason || '(none)'} duration=${duration}s`, ) if (entry) { entry.unsub() clearInterval(entry.keepalive) cleanupBySession.delete(sessionId) } } /** * Derive event type from a child process message that may lack an explicit * `type` field. The child's --print --output-format stream-json mode sends: * {"message":{"role":"user",...},"uuid":"..."} → type "user" * {"message":{"role":"assistant",...},"uuid":"..."} → type "assistant" * {"subtype":"success","uuid":"...","result":"..."} → type "result" */ function deriveEventType(msg: Record): string { if (msg.type && typeof msg.type === 'string') return msg.type // Child process stream-json format: message.role determines type const message = msg.message as Record | undefined if (message && typeof message.role === 'string') { return message.role // "user", "assistant", "system" } // Result message if (msg.subtype || msg.result !== undefined) return 'result' // System/init message if (msg.session_id) return 'system' return 'unknown' } /** * Fields of a system/init message that remote clients (Web UI) consume: * command/skill tables for the dynamic slash-command menu, and the worker's * Remote Control capability set (which control_request subtypes it handles) * for UI gating. Preserved verbatim — shape validation lives client-side * (parseRemoteCapabilities) so the relay stays permissive for new fields. */ function preserveSystemInitFields( msg: Record, ): Record { const out: Record = {} if (Array.isArray(msg.slash_commands)) out.slash_commands = msg.slash_commands if (Array.isArray(msg.slash_command_details)) out.slash_command_details = msg.slash_command_details if (Array.isArray(msg.skills)) out.skills = msg.skills if (Array.isArray(msg.skill_details)) out.skill_details = msg.skill_details if ( msg.remote_capabilities && typeof msg.remote_capabilities === 'object' && !Array.isArray(msg.remote_capabilities) ) { out.remote_capabilities = msg.remote_capabilities } return out } /** * Parse a single SDK message from bridge -> publish to EventBus as inbound. * * Dedup guard: the child process (spawned with --replay-user-messages) echoes * replayed history back on WS (re)connect. Without dedup, each reconnect * multiplies the inbound events in the bus → web UI shows duplicate messages. * - User-message acks carry isReplay:true (fast-path skip). * - Assistant-message echoes reuse the original UUID (UUID-based skip). */ export function ingestBridgeMessage( sessionId: string, msg: Record, ) { if (msg.type === 'keep_alive') return // Fast path: child explicitly marks this as a replay ack — skip. if (msg.isReplay === true) { log( `[RC-DEBUG] [WS] Skipping replay ack: sessionId=${sessionId} uuid=${msg.uuid ?? '(none)'}`, ) return } const eventType = deriveEventType(msg) // UUID-based dedup: child echoes replayed assistant/system messages back // with the original UUID. If the bus already has that UUID, this is an echo. const msgUuid = typeof msg.uuid === 'string' ? msg.uuid : null if (msgUuid) { const bus = getEventBus(sessionId) if (bus.hasEventWithUuid(msgUuid)) { log( `[RC-DEBUG] [WS] Dedup: skipping already-published event type=${eventType} uuid=${msgUuid}`, ) return } } // CLI worker's own /clear → SDKStatusMessage (type 'status', status // 'conversation_cleared'). Wipe the session's persisted + in-memory history // and notify live web viewers, mirroring POST /web/sessions/:id/clear. The // raw status event must NOT be published — it would land in the fresh event // log and the web adapter ignores 'status' events anyway. if (eventType === 'status' && msg.status === 'conversation_cleared') { log( `[RC-DEBUG] [WS] Worker /clear (conversation_cleared): wiping conversation session=${sessionId}`, ) wipeSessionConversation(sessionId) return } log( `[RC-DEBUG] [WS] <- bridge (inbound): sessionId=${sessionId} type=${eventType}${msg.uuid ? ` uuid=${msg.uuid}` : ''} msg=${JSON.stringify(msg).slice(0, 300)}`, ) let payload: unknown if (eventType === 'assistant' || eventType === 'partial_assistant') { const message = msg.message as Record | undefined const content = message?.content // Extract text from content blocks for simple display let text = '' if (typeof content === 'string') { text = content } else if (Array.isArray(content)) { text = content .filter( (b: unknown) => b && typeof b === 'object' && 'type' in (b as Record) && (b as Record).type === 'text', ) .map( (b: Record) => (b as Record).text || '', ) .join('') } payload = { message: msg.message, uuid: msg.uuid, content: text } } else if (eventType === 'user') { payload = { message: msg.message, uuid: msg.uuid, ...(typeof msg.isSynthetic === 'boolean' ? { isSynthetic: msg.isSynthetic } : {}), } } else if (eventType === 'system') { // SDK events (task_started/task_progress/task_notification/session_state_changed) // carry subagent panel state in their own fields, not under `message`. // Preserve those fields so the web UI can render the subagent panel. // Generic system messages (e.g. init) still keep message/uuid/isSynthetic. const subtype = typeof msg.subtype === 'string' ? msg.subtype : undefined const isSdkTaskEvent = subtype === 'task_started' || subtype === 'task_progress' || subtype === 'task_notification' || subtype === 'session_state_changed' if (isSdkTaskEvent) { payload = { ...msg } delete (payload as Record).type } else { payload = { message: msg.message, uuid: msg.uuid, ...(typeof msg.isSynthetic === 'boolean' ? { isSynthetic: msg.isSynthetic } : {}), ...(subtype ? { subtype } : {}), // system/status messages carry the CLI's current permission mode — // keep it so the web UI mode indicator stays in sync. ...(typeof msg.permissionMode === 'string' ? { permissionMode: msg.permissionMode } : {}), // system/init carries the worker's command/skill tables and Remote // Control capability set — the Web UI's dynamic command menu and // per-worker UI gating consume them. Only preserved for init; other // system subtypes never carry these fields. ...(subtype === 'init' ? preserveSystemInitFields(msg) : {}), } } } else if (eventType === 'control_request') { payload = { request_id: msg.request_id, request: msg.request } } else if (eventType === 'control_response') { // Pending server-side title requests settle here (request_id match). handleTitleControlResponse(sessionId, msg.response) payload = { response: msg.response } } else if (eventType === 'result' || eventType === 'result_success') { // Keep usage/cost so the web UI can render cumulative session totals // (mirrors the CLI StatusLine), and result/is_error so error-subtyped // results (worker crash / timeout exit signal) render their reason. payload = { subtype: msg.subtype, uuid: msg.uuid, result: msg.result, ...(msg.is_error !== undefined ? { is_error: msg.is_error } : {}), ...(msg.total_cost_usd !== undefined ? { total_cost_usd: msg.total_cost_usd } : {}), ...(msg.usage && typeof msg.usage === 'object' ? { usage: msg.usage } : {}), } } else { payload = msg } publishSessionEvent(sessionId, eventType, payload, 'inbound') // 待批权限记账 —— 与 v2 worker-events 路径保持同一语义。 const permissionRequest = eventType === 'control_request' ? (msg.request as Record | undefined) : undefined if (permissionRequest?.subtype === 'can_use_tool') { registerPendingPermission( sessionId, typeof msg.request_id === 'string' ? msg.request_id : '', { toolName: typeof permissionRequest.tool_name === 'string' ? permissionRequest.tool_name : undefined, toolInput: (permissionRequest.input ?? permissionRequest.tool_input) as | Record | undefined, description: typeof permissionRequest.description === 'string' ? permissionRequest.description : undefined, suggestions: Array.isArray(permissionRequest.permission_suggestions) ? permissionRequest.permission_suggestions : undefined, toolUseId: typeof permissionRequest.tool_use_id === 'string' ? permissionRequest.tool_use_id : undefined, }, ) } else if (eventType === 'control_response') { const response = msg.response as Record | undefined if (typeof response?.request_id === 'string') { resolvePendingPermission(sessionId, response.request_id) settlePermissionStatus(sessionId) } } else if (eventType === 'control_cancel_request') { if (typeof msg.request_id === 'string') { resolvePendingPermission(sessionId, msg.request_id) settlePermissionStatus(sessionId) } } else if (eventType === 'result' || eventType === 'result_success') { clearPendingPermissions(sessionId) } // V1 transport's reportState is a no-op (replBridgeTransport.ts:98), so // the server derives session status from the inbound event flow — mirrors // what V2's WorkerStateUploader pushes via PUT /worker. result/result_success // → idle (turn done), control_request → requires_action (permission pending), // assistant → running (LLM streaming). Skip when the session isn't in the // store (test fixtures) or status is already the target so streaming // assistant chunks don't spam session_status events. // // Turn-signal accounting (EventBus.turnActive): the REPL bridge can POST // the synthetic turn-end result BEFORE the final mirrored assistant // message (transcript-mirror render race in useReplBridge / flush-gate // bypass in replBridge.writeMessages). A late assistant must not flip // the session back to running after the turn ended — the web UI input // would re-engage and every new message would land in the queue. const bus = getEventBus(sessionId) if (eventType === 'user') { bus.turnActive = true } else if (eventType === 'result' || eventType === 'result_success') { bus.turnActive = false } const session = getSession(sessionId) const targetStatus = eventType === 'result' || eventType === 'result_success' ? 'idle' : eventType === 'control_request' ? 'requires_action' : eventType === 'assistant' && bus.turnActive ? 'running' : null if (session && targetStatus && session.status !== targetStatus) { updateSessionStatus(sessionId, targetStatus) } // First completed turn on an untitled session — ask the worker for a title // (both worker backends implement generate_session_title via the shared // control dispatcher; an error reply means the worker's own generation // failed — see services/session-titles.ts). if (eventType === 'result' || eventType === 'result_success') { maybeRequestSessionTitle(sessionId) } } /** * Gracefully close all active WebSocket connections. */ export function closeAllConnections(): void { const count = activeConnections.size if (count === 0) return log(`[WS] Gracefully closing ${count} active connection(s)...`) for (const [sessionId, entry] of cleanupBySession) { try { entry.unsub() clearInterval(entry.keepalive) if (entry.ws.readyState === 1) { entry.ws.close(1001, 'server_shutdown') } } catch { // ignore errors during shutdown } } cleanupBySession.clear() activeConnections.clear() log('[WS] All connections closed') }