Skip to content

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

56.9 KB
Raw Blame
//! Socket.IO live-event bridge to the desktop shell.
//!
//! `spawn_web_channel_bridge` spawns one forwarding task per source. Domain
//! broadcast channels: web-chat events (`openhuman::web_chat`), core
//! notifications (`openhuman::desktop::notifications`), and shell companion state
//! (`COMPANION_STATE_BUS`). `DomainEvent`s read off `openhuman::core::bus::BUS`:
//! session expiry, MCP setup secret requests, memory sync and tree-build
//! progress, channel listener health, and active-workspace changes. Web-chat
//! events go to the initiating client's room and the `thread:<id>` room
//! (`emit_web_channel_event`); everything else is broadcast to every
//! connected client, most under both a colon- and an underscore-separated
//! event name for frontend compatibility. `COMPANION_STATE_BUS` is a broadcast
//! channel dedicated to shell-originated companion lifecycle events: the
//! companion implementation itself lives in the Tauri shell; companion
//! clients that use Socket.IO receive lifecycle state through this
//! transport-only seam rather than a core-side companion domain.
//!
//! The socketioxide/axum transport bodies (the actual `SocketIo` server,
//! connection handlers, and `spawn_web_channel_bridge`) are gated behind the
//! `http-server` feature (#5048). The event payload types further down
//! (`WebChannelEvent`, `TurnUsagePayload`, `SubagentUsagePayload`,
//! `SubagentProgressDetail`) stay compiled in every build regardless — around
//! ten always-on domains (`web_chat`, `cron`, `channels`, `agent`, …)
//! construct them — so only the transport surface is gated, not the types
//! (a "type carve-out"; see AGENTS.md). `pub mod socketio;` in `core::mod` is
//! intentionally NOT gated for the same reason.

use serde::Deserialize;
use serde::Serialize;
use serde_json::json;
use serde_json::Value;
use socketioxide::extract::{AckSender, Data, SocketRef, TryData};
use socketioxide::SocketIo;

use crate::core_host::web_chat::{GuardrailPayload, ScopedWebEvent};

/// Shell-originated companion lifecycle events that still need to reach
/// Companion clients that receive lifecycle state through Socket.IO.
static COMPANION_STATE_BUS: once_cell::sync::Lazy<tokio::sync::broadcast::Sender<Value>> =
    once_cell::sync::Lazy::new(|| {
        let (tx, _rx) = tokio::sync::broadcast::channel(64);
        tx
    });

/// Publish a shell-side companion state payload for Socket.IO clients.
///
/// The companion implementation lives in the Tauri shell. Keeping this
/// transport-only seam here avoids reintroducing the removed core companion
/// domain.
pub fn publish_companion_state_changed(payload: Value) -> usize {
    COMPANION_STATE_BUS.send(payload).unwrap_or_default()
}

fn subscribe_companion_state_changed() -> tokio::sync::broadcast::Receiver<Value> {
    COMPANION_STATE_BUS.subscribe()
}

/// Marker stored in [`SocketRef::extensions`] once a connection has presented a
/// bearer token that matches the active per-process RPC token.
///
/// Event handlers consult this before forwarding attacker-controllable input
/// into the JSON-RPC dispatcher or the web-chat orchestrator: an unauthenticated
/// socket that never picked up the marker is allowed to receive broadcast-style
/// events (read-only) but cannot trigger executable work.
#[derive(Clone, Copy, Debug)]
struct AuthedConnection;

/// Tenant captured from the server-side context when the socket connects.
/// The per-process bearer authenticates the connection but does not encode a
/// SaaS profile, so never accept tenant selection from a later event payload.
#[derive(Clone, Debug)]
struct SocketTenant(crate::core_host::agent::plan_review::SocketReviewScope);

/// Bind replay tenancy from the HTTP request extensions retained by
/// Socket.IO. Its async connect callback is spawned independently of the
/// Axum request task, so task-local ambient context is not a reliable carrier.
fn socket_tenant_from_request_extensions(
    extensions: &axum::http::Extensions,
) -> Option<SocketTenant> {
    let dispatch = extensions.get::<crate::core_host::core::runtime::DispatchCtx>()?;
    let scope = crate::core_host::agent::plan_review::socket_scope_for_dispatch(dispatch)?;
    Some(SocketTenant(scope))
}

/// Connection-time payload the client passes via Socket.IO's `auth` field.
///
/// Browsers do not let `EventSource` / `WebSocket` clients attach custom
/// headers, so the handshake `auth` map is the only header-equivalent slot
/// available for our per-process bearer. The socket-IO Node/JS clients all
/// surface `io(url, { auth: { token: "<hex>" } })` for this.
#[derive(Debug, Default, Deserialize)]
struct HandshakeAuth {
    #[serde(default)]
    token: Option<String>,
}

/// Origins the local core trusts at the Socket.IO handshake.
///
/// The document origin of the CEF-served app shell is platform-dependent:
///
/// | Platform | Scheme | Host |
/// |----------|--------|------|
/// | macOS / iOS (native scheme) | `tauri` | `localhost` |
/// | Windows (CEF http custom protocol) | `http` | `tauri.localhost` |
/// | Linux / older Windows builds | `https` | `tauri.localhost` |
/// | Vite dev (`pnpm dev:app`, `pnpm dev`) | `http` | `localhost` / `127.0.0.1` / `[::1]` |
///
/// The handshake `Origin` header is stamped by the webview with whichever
/// of these shapes loaded the page — it is **not** the destination URL the
/// socket is connecting to. We match the parsed host against the allowlist
/// so all four shapes pass regardless of scheme, while `starts_with` decoys
/// like `http://localhost.attacker.example` are still rejected (parser
/// returns a different `host_str`).
///
/// A missing `Origin` header is treated as a native (non-browser) client
/// and accepted — only the cross-origin browser-page case is the targeted
/// bad actor here.
pub(crate) fn origin_is_allowed(origin: Option<&str>) -> bool {
    origin_is_allowed_with_extra(
        origin,
        std::env::var(crate::ALLOWED_ORIGINS_ENV).ok().as_deref(),
    )
}

/// Origin gate with the extra allowlist passed explicitly so tests do not have
/// to mutate process-global env.
///
/// Chat is a socket-only transport (`chat:start` / `chat:cancel`) with no
/// JSON-RPC equivalent. Before this consulted `OPENHUMAN_CORE_ALLOWED_ORIGINS`,
/// a non-loopback browser origin that the RPC CORS layer already accepted was
/// still dropped here: the page loaded and every read RPC succeeded, but the
/// socket was disconnected at handshake and pressing Send did nothing, with no
/// error surfaced to the user.
pub(crate) fn origin_is_allowed_with_extra(
    origin: Option<&str>,
    extra_origins: Option<&str>,
) -> bool {
    let Some(origin) = origin else {
        return true; // native clients (CLI, Tauri shell) — no Origin header
    };
    let origin = origin.trim();
    if origin.is_empty() || origin == "null" {
        return false;
    }
    // Parse the URL and compare the host EXACTLY against the loopback +
    // tauri.localhost allowlist. The earlier scheme-literal short-circuit
    // (`tauri://localhost` / `https://tauri.localhost`) missed
    // `http://tauri.localhost`, which is the document origin CEF stamps
    // on Windows — every flavour of the Tauri webview shell now goes
    // through the same host check.
    let Ok(parsed) = url::Url::parse(origin) else {
        return false;
    };
    // `url::Url::host_str` returns IPv6 hosts with surrounding brackets,
    // hostnames bare. Accept both shapes.
    if matches!(
        parsed.host_str(),
        Some("localhost" | "127.0.0.1" | "::1" | "[::1]" | "tauri.localhost")
    ) {
        return true;
    }

    // Operator-controlled extra origins. Exact string match, same rule as the
    // JSON-RPC layer — no host-only or prefix matching, so the decoy cases
    // below stay rejected even when the allowlist is populated.
    if let Some(extra) = extra_origins {
        for candidate in extra.split(',').map(str::trim).filter(|s| !s.is_empty()) {
            if candidate == origin {
                return true;
            }
        }
    }

    false
}

/// True when `socket` finished the handshake with a valid bearer token.
fn socket_is_authed(socket: &SocketRef) -> bool {
    socket.extensions.get::<AuthedConnection>().is_some()
}

/// Best-effort disconnect. Called when we discover an unauthenticated socket
/// inside an event handler — the connect path already disconnects the bad
/// origins / wrong tokens, so this is purely a defense-in-depth path.
fn drop_unauthed(socket: &SocketRef, reason: &'static str) {
    log::warn!(
        "[socketio] dropping unauthenticated socket id={} reason={}",
        socket.id,
        reason
    );
    let _ = socket.clone().disconnect();
}

#[derive(Debug, Deserialize)]
struct SocketRpcRequest {
    id: serde_json::Value,
    method: String,
    #[serde(default)]
    params: serde_json::Value,
}

#[derive(Debug, Deserialize)]
struct ChatStartPayload {
    thread_id: String,
    message: String,
    #[serde(default)]
    model: Option<String>,
    #[serde(default)]
    model_override: Option<String>,
    #[serde(default)]
    temperature: Option<f64>,
    #[serde(default)]
    locale: Option<String>,
    #[serde(default)]
    queue_mode: Option<String>,
    /// Optional `"plan"` | `"build"` — lets the composer start this turn with
    /// the thread already in the requested run mode (e.g. a "Plan" toggle),
    /// rather than a separate `agent.set_run_mode` round-trip racing the
    /// `chat:start` itself. Unrecognized values are ignored (logged), not
    /// rejected — a stale/typo'd client build should not fail the whole turn.
    #[serde(default)]
    run_mode: Option<String>,
}

#[derive(Debug, Deserialize)]
struct ChatCancelPayload {
    thread_id: String,
    /// The request this cancel targets. When the client passes the id of the
    /// turn it started, the cancel is scoped to that turn so a late cancel for a
    /// timed-out request can't kill the next turn on the thread (#4760).
    #[serde(default)]
    request_id: Option<String>,
}

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct ThreadSubscribePayload {
    thread_id: String,
}

/// Reply to `thread:subscribe`, so a client can order a read after the join.
#[derive(Debug, Serialize)]
struct ThreadSubscribeAck {
    joined: bool,
}

/// Attaches the Socket.IO layer to the Axum router and sets up event handlers.
///
/// It configures:
/// - Client connection and room joining.
/// - `rpc:request`: Invoking JSON-RPC methods over WebSocket.
/// - `chat:start`: Initiating a new chat turn.
/// - `chat:cancel`: Aborting an active chat turn.
pub fn attach_socketio() -> (socketioxide::layer::SocketIoLayer, SocketIo) {
    let (layer, io) = SocketIo::new_layer();

    log::info!(
        "[socketio] engine ready (namespace /, path {})",
        io.config().engine_config.req_path
    );

    io.ns(
        "/",
        |socket: SocketRef, TryData(handshake): TryData<HandshakeAuth>| {
            let client_id = socket.id.to_string();

            // Reject cross-origin browser pages before the handshake completes.
            // Native clients (Tauri shell, CLI) do not set an `Origin` header and
            // are accepted; only browser pages from origins outside the local
            // app surface are dropped here. See `origin_is_allowed`.
            let origin = socket
                .req_parts()
                .headers
                .get(axum::http::header::ORIGIN)
                .and_then(|v| v.to_str().ok())
                .map(|s| s.to_string());
            if !origin_is_allowed(origin.as_deref()) {
                log::warn!(
                    "[socketio] rejecting connect: bad origin {:?} client={}",
                    origin,
                    client_id
                );
                let _ = socket.clone().disconnect();
                return;
            }

            // Verify the handshake bearer matches the per-process RPC token.
            // `TryData` lets us treat a missing/malformed `auth` payload as a
            // soft failure (no panic) and reject the connect cleanly.
            let supplied = handshake.ok().and_then(|h| h.token).unwrap_or_default();
            if !crate::core_host::core::auth::verify_bearer_token(&supplied) {
                log::warn!(
                    "[socketio] rejecting connect: missing or invalid bearer client={}",
                    client_id
                );
                let _ = socket.clone().disconnect();
                return;
            }
            socket.extensions.insert(AuthedConnection);
            let Some(tenant) = socket_tenant_from_request_extensions(
                &socket.req_parts().extensions,
            ) else {
                log::warn!("[socketio] rejecting socket without a tenant scope in SaaS mode");
                let _ = socket.clone().disconnect();
                return;
            };
            socket.extensions.insert(tenant);

            log::info!("[socketio] client connected id={client_id} (authenticated)");
            // Join a room named after the client ID for targeted event delivery.
            let _ = join_room_logged(&socket, &client_id, &client_id);
            // Also auto-join the "system" room so every connected client
            // receives broadcast-style events that aren't tied to a
            // specific chat thread. Today this covers proactive messages
            // (welcome agent, morning briefing, cron-driven announcements)
            // which `web_chat::proactive::WebProactiveSubscriber` emits with
            // `client_id = "system"` — see `emit_web_channel_event`.
            // If this join fails the welcome message silently disappears,
            // so we log both success and failure for diagnosability.
            let _ = join_room_logged(&socket, "system", &client_id);
            let ready_payload = json!({ "sid": client_id });
            log::debug!("[socketio] emit event=ready to_client={}", socket.id);
            let _ = socket.emit("ready", &ready_payload);

            // Seed this client with the workspace that is current (#5966).
            // The `workspace_changed` bridge in `spawn_web_channel_bridge`
            // only fires on a switch, so a client that connects between
            // switches — the common case, since the app connects at launch —
            // would otherwise have no idea which workspace is active and
            // could not scope anything.
            //
            // Spawned because this handler is synchronous and the resolve is
            // not. Emitting to `socket` rather than broadcasting keeps a
            // late-joining client from re-announcing a workspace every other
            // client already knows about.
            {
                let socket = socket.clone();
                let client_id = client_id.clone();
                tokio::spawn(async move {
                    match crate::core_host::config::active_workspace_snapshot().await {
                        Ok((dir, revision)) => {
                            let handle = crate::core_host::config::workspace_handle(&dir);
                            // One snapshot, not two reads: resolved
                            // separately, a switch between them would pair
                            // this workspace with the *next* one's revision,
                            // and the client would rank a stale seed above
                            // the switch it lost to. This task and the switch
                            // bridge are separate, so that race is real; the
                            // client keeps the highest revision it has seen.
                            log::debug!(
                                "[socketio] emit event=workspace_changed to_client={client_id} workspace={handle} revision={revision}"
                            );
                            let payload =
                                json!({ "workspace": handle, "revision": revision });
                            let _ = socket.emit("workspace_changed", &payload);
                            let _ = socket.emit("workspace:changed", &payload);
                        }
                        Err(error) => log::warn!(
                            "[socketio] could not resolve the active workspace to seed client={client_id}: {error}"
                        ),
                    }
                });
            }

            // Handler for JSON-RPC over WebSocket.
            socket.on(
                "rpc:request",
                |socket: SocketRef, Data(payload): Data<SocketRpcRequest>| async move {
                    if !socket_is_authed(&socket) {
                        drop_unauthed(&socket, "rpc:request from unauthenticated socket");
                        return;
                    }
                    let client_id = socket.id.to_string();
                    log::info!(
                        "[socketio] rpc:request method={} id={} client={}",
                        payload.method,
                        payload.id,
                        client_id
                    );

                    // Invoke the method through the same logic used by the HTTP RPC endpoint.
                    let response = match crate::core_host::core::invoke::invoke_method(
                        // A Socket.IO event is not scoped to a request, so it
                        // runs under the process default context.
                        crate::core_host::core::runtime::DispatchCtx::process_default(),
                        crate::core_host::core::invoke::default_state(),
                        payload.method.as_str(),
                        payload.params,
                    )
                    .await
                    {
                        Ok(result) => (
                            "rpc:response",
                            json!({ "id": payload.id, "result": result }),
                        ),
                        Err(message) => (
                            "rpc:error",
                            json!({
                                "id": payload.id,
                                "error": { "code": -32000, "message": message }
                            }),
                        ),
                    };

                    let _ = socket.emit(response.0, &response.1);
                },
            );

            // Handler for starting a chat turn.
            socket.on(
                "chat:start",
                |socket: SocketRef, Data(payload): Data<ChatStartPayload>| async move {
                    if !socket_is_authed(&socket) {
                        drop_unauthed(&socket, "chat:start from unauthenticated socket");
                        return;
                    }
                    let client_id = socket.id.to_string();
                    let thread_id = payload.thread_id.clone();
                    let model_override = payload.model_override.or(payload.model);
                    log::debug!(
                    "[socketio] recv event=chat:start client_id={} thread_id={} message_bytes={}",
                    client_id,
                    thread_id,
                    payload.message.len()
                );
                    if let Some(run_mode) = payload.run_mode.as_deref() {
                        match crate::core_host::agent::tinyagents::run_mode::parse_mode_label(run_mode) {
                            Some(mode) => {
                                crate::core_host::agent::tinyagents::run_mode::set_mode(
                                    &crate::core_host::core::runtime::DispatchCtx::host_default(),
                                    &thread_id,
                                    mode,
                                );
                            }
                            None => log::warn!(
                                "[socketio] chat:start thread_id={thread_id} ignoring unrecognized run_mode={run_mode}"
                            ),
                        }
                    }

                    // Trigger the web channel's chat logic.
                    match crate::core_host::web_chat::start_chat(
                        // Outside SaaS the host's one context; in SaaS the socket task's own scope.
                        &crate::core_host::core::runtime::DispatchCtx::host_default(),
                        &client_id,
                        &payload.thread_id,
                        &payload.message,
                        model_override,
                        payload.temperature,
                        payload.locale,
                        payload.queue_mode,
                        crate::core_host::web_chat::ChatRequestMetadata::default(),
                    )
                    .await
                    {
                        Ok(request_id) => {
                            let accepted_payload = json!({
                                "event": "chat_accepted",
                                "client_id": client_id,
                                "thread_id": thread_id,
                                "request_id": request_id,
                            });
                            emit_with_aliases(&socket, "chat_accepted", &accepted_payload);
                        }
                        Err(error) => {
                            let mut error_payload = json!({
                                "event": "chat_error",
                                "client_id": client_id,
                                "thread_id": thread_id,
                                "request_id": "",
                                "message": error.to_string(),
                                "error_type": "inference",
                            });
                            // A guardrail rejection is structured (verdict/
                            // score/reasons), not just a user-facing message —
                            // surface it the same way the frontend classifies
                            // every other `chat_error`: by `error_type`, plus
                            // a typed `guardrail` payload it doesn't have to
                            // parse out of `message`.
                            if let crate::core_host::web_chat::StartChatError::Guardrail {
                                verdict,
                                score,
                                reasons,
                            } = &error
                            {
                                error_payload["error_type"] = json!("guardrail");
                                error_payload["guardrail"] = json!(GuardrailPayload {
                                    verdict: verdict.clone(),
                                    score: *score,
                                    reasons: reasons.clone(),
                                });
                            }
                            emit_with_aliases(&socket, "chat_error", &error_payload);
                        }
                    }
                },
            );

            // Handler for cancelling an active chat turn.
            socket.on(
                "chat:cancel",
                |socket: SocketRef, Data(payload): Data<ChatCancelPayload>| async move {
                    if !socket_is_authed(&socket) {
                        drop_unauthed(&socket, "chat:cancel from unauthenticated socket");
                        return;
                    }
                    let client_id = socket.id.to_string();
                    log::debug!(
                        "[socketio] recv event=chat:cancel client_id={} thread_id={}",
                        client_id,
                        payload.thread_id
                    );
                    let _ = crate::core_host::web_chat::cancel_chat_scoped(
                        &crate::core_host::core::runtime::DispatchCtx::host_default(),
                        &client_id,
                        &payload.thread_id,
                        payload.request_id.as_deref(),
                    )
                    .await;
                },
            );

            // Handler for subscribing this socket to a thread's room.
            //
            // Chat-stream events are delivered to BOTH the initiating client's
            // own room AND a per-thread room (`thread:<id>`). After a socket
            // reconnects it has a NEW client_id, so it would miss an in-flight
            // turn's remaining stream (delivered to the OLD client_id room). The
            // frontend emits this on connect/reconnect for the active thread, so
            // the new socket re-joins the thread room and keeps receiving the
            // stream. Membership is dropped automatically on disconnect.
            //
            // The join is acknowledged so a client can *order* work against it.
            // A reconnecting client re-reads the thread to pick up a reply that
            // landed while it was away (#6034); firing that read before the join
            // is processed leaves a window where the read misses the row and the
            // turn's `chat_done` is emitted to a room this socket has not joined
            // yet, so the reply stays invisible until a manual reload. The ack
            // closes it. Clients that ignore the ack are unaffected — an unused
            // acknowledgement is inert.
            socket.on(
                "thread:subscribe",
                |socket: SocketRef, Data(payload): Data<ThreadSubscribePayload>, ack: AckSender| async move {
                    if !socket_is_authed(&socket) {
                        drop_unauthed(&socket, "thread:subscribe from unauthenticated socket");
                        return;
                    }
                    let thread_id = payload.thread_id.trim();
                    if thread_id.is_empty() {
                        // Still acknowledge: a client awaiting this must not be
                        // left hanging on its own malformed payload.
                        ack.send(&ThreadSubscribeAck { joined: false }).ok();
                        return;
                    }
                    let room = format!("thread:{thread_id}");
                    // Report what actually happened. Acknowledging a join that
                    // failed is worse than not acknowledging at all: the client
                    // stops queueing the thread for retry and reads on the
                    // strength of a room it is not in.
                    let joined = join_room_logged(&socket, &room, &socket.id.to_string());
                    // Hand this socket whatever the approval gate still has
                    // parked on the thread, BEFORE acknowledging the join, so a
                    // client that orders its recovery reads against the ack
                    // already holds the card.
                    if joined {
                        replay_parked_approval(&socket, thread_id);
                        replay_parked_plan_review(&socket, thread_id);
                    }
                    ack.send(&ThreadSubscribeAck { joined }).ok();
                },
            );
        },
    );

    (layer, io)
}

/// Spawns background bridges to forward various system events to Socket.IO clients.
///
/// This function sets up event bridges:
/// 1. **Web Channel Bridge**: Forwards chat-related events (messages, tool calls) to specific clients.
/// 3. **Overlay Bridge**: Forwards attention bubble events to all clients.
/// 4. **Core Notification Bridge**: Forwards core notification events to all clients.
pub fn spawn_web_channel_bridge(io: SocketIo) {
    // 1. Web channel events → per-client rooms.
    let io_web = io.clone();
    tokio::spawn(async move {
        let mut rx = crate::core_host::web_chat::subscribe_web_channel_events();
        loop {
            let event = match rx.recv().await {
                Ok(event) => event,
                Err(tokio::sync::broadcast::error::RecvError::Lagged(skipped)) => {
                    log::warn!("[socketio] dropped {skipped} web channel events due to lag");
                    continue;
                }
                Err(tokio::sync::broadcast::error::RecvError::Closed) => break,
            };

            emit_web_channel_event(&io_web, event);
        }
        log::debug!("[socketio] web_channel bridge stopped");
    });

    let io_notify = io.clone();
    let io_auth = io.clone();
    let io_memory_sync = io.clone();
    let io_channel_status = io.clone();
    let io_companion = io.clone();
    let io_workspace = io.clone();

    // Shell companion state → broadcast to Socket.IO clients. The main
    // renderer also receives a Tauri event directly.
    tokio::spawn(async move {
        let mut rx = subscribe_companion_state_changed();
        loop {
            let payload = match rx.recv().await {
                Ok(payload) => payload,
                Err(tokio::sync::broadcast::error::RecvError::Lagged(skipped)) => {
                    log::warn!(
                        "[socketio] dropped {} companion state_changed events due to lag",
                        skipped
                    );
                    continue;
                }
                Err(tokio::sync::broadcast::error::RecvError::Closed) => break,
            };
            log::debug!("[socketio] broadcast companion:state_changed");
            let _ = io_companion.emit("companion:state_changed", &payload);
            let _ = io_companion.emit("companion_state_changed", &payload);
        }
        log::debug!("[socketio] companion state bridge stopped");
    });

    // 3. Core notification events → broadcast to all connected clients so
    //    the in-app notification center picks them up regardless of which
    //    chat session is active. This is a fire-and-forget broadcast with no
    //    per-client routing.
    tokio::spawn(async move {
        let mut rx = crate::core_host::desktop::notifications::subscribe_core_notifications();
        loop {
            let event = match rx.recv().await {
                Ok(event) => event,
                Err(tokio::sync::broadcast::error::RecvError::Lagged(skipped)) => {
                    log::warn!("[socketio] dropped {skipped} events due to lag");
                    continue;
                }
                Err(tokio::sync::broadcast::error::RecvError::Closed) => break,
            };

            if let Ok(payload) = serde_json::to_value(&event) {
                log::debug!(
                    "[socketio] broadcast core_notification id={} category={:?}",
                    event.id,
                    event.category
                );
                let _ = io_notify.emit("core_notification", &payload);
                let _ = io_notify.emit("core:notification", &payload);
            }
        }
        log::debug!("[socketio] core_notification bridge stopped");
    });

    // 5. SessionExpired events → broadcast to all clients so the UI can
    //    proactively tear down user-scoped state and route to onboarding
    //    instead of waiting for the next poll to discover the JWT is gone.
    //    Subscribes to the global event bus and filters for
    //    `DomainEvent::SessionExpired`; ignores everything else.
    tokio::spawn(async move {
        // Poll until `event_bus::init_global` has run. Socket.IO bridges
        // spawn from `spawn_web_channel_bridge`, which on some startup
        // paths runs before `register_domain_subscribers` initialises
        // the bus. A one-shot check would silently no-op for the rest
        // of the process; a short polling loop with a hard cap retries
        // without spinning forever if init genuinely never happens
        // (e.g. tests that drive the socket layer in isolation).
        let bus = {
            const RETRY_INTERVAL_MS: u64 = 250;
            const MAX_WAIT_SECS: u64 = 30;
            let max_attempts = (MAX_WAIT_SECS * 1000) / RETRY_INTERVAL_MS;
            let mut attempts: u64 = 0;
            loop {
                if let Some(bus) = crate::core_host::core::bus::BUS.get() {
                    break bus;
                }
                attempts += 1;
                if attempts > max_attempts {
                    log::warn!(
                        "[socketio] event_bus not initialised after {}s — SessionExpired bridge giving up",
                        MAX_WAIT_SECS
                    );
                    return;
                }
                tokio::time::sleep(std::time::Duration::from_millis(RETRY_INTERVAL_MS)).await;
            }
        };
        let mut rx = bus.receiver();
        loop {
            let Some(event) = rx.recv().await else {
                break;
            };
            if let crate::core_host::core::events::DomainEvent::SessionExpired { source, reason } =
                event
            {
                // Other publishers may emit a backend 401 while this core is
                // using its offline local credential. The auth subscriber
                // correctly keeps that credential, so the UI must not receive
                // a contradictory sign-out event from this independent bus
                // consumer. Real JWT expiry still broadcasts as before.
                if crate::core_host::security::credentials::session_support::current_session_is_local(
                    &crate::core_host::core::runtime::DispatchCtx::process_default(),
                )
                .await
                {
                    log::info!(
                        "[socketio] suppress auth:session_expired for local offline credential source={}",
                        source
                    );
                    continue;
                }
                log::info!(
                    "[socketio] broadcast auth:session_expired source={} reason_len={}",
                    source,
                    reason.len()
                );
                // The UI doesn't need the raw reason (already logged
                // server-side and we don't want auth-error strings in the
                // renderer console). Just send the source slug.
                let payload = serde_json::json!({ "source": source });
                let _ = io_auth.emit("auth:session_expired", &payload);
                let _ = io_auth.emit("auth_session_expired", &payload);
            }
        }
        log::debug!("[socketio] auth session_expired bridge stopped");
    });

    // 6a. ActiveWorkspaceChanged → broadcast `workspace_changed` carrying the
    //     new workspace's opaque handle (#5966).
    //
    //     `core_notification` is emitted to every connected client with no
    //     per-client routing, and the publish-time gate that decides whether a
    //     workspace-bound notification may be broadcast resolves the active
    //     workspace and then sends — two steps, not one. A switch in between
    //     still lets one through. Telling clients the handle of the workspace
    //     that is current lets the receiver re-check on render instead of
    //     trusting a boolean taken at an instant.
    //
    //     The handle, never `workspace_dir`: this reaches every connected
    //     client and the path is under the user's home directory.
    tokio::spawn(async move {
        let bus = {
            const RETRY_INTERVAL_MS: u64 = 250;
            const MAX_WAIT_SECS: u64 = 30;
            let max_attempts = (MAX_WAIT_SECS * 1000) / RETRY_INTERVAL_MS;
            let mut attempts: u64 = 0;
            loop {
                if let Some(bus) = crate::core_host::core::bus::BUS.get() {
                    break bus;
                }
                attempts += 1;
                if attempts > max_attempts {
                    log::warn!(
                        "[socketio] event_bus not initialised after {}s — workspace bridge giving up",
                        MAX_WAIT_SECS
                    );
                    return;
                }
                tokio::time::sleep(std::time::Duration::from_millis(RETRY_INTERVAL_MS)).await;
            }
        };
        let mut rx = bus.receiver();
        loop {
            let Some(event) = rx.recv().await else {
                break;
            };
            if let crate::core_host::core::events::DomainEvent::ActiveWorkspaceChanged {
                workspace_dir,
                revision,
            } = event
            {
                let handle = crate::core_host::config::workspace_handle(&workspace_dir);
                log::info!(
                    "[socketio] broadcast workspace_changed workspace={handle} revision={revision}"
                );
                let payload = serde_json::json!({ "workspace": handle, "revision": revision });
                let _ = io_workspace.emit("workspace_changed", &payload);
                let _ = io_workspace.emit("workspace:changed", &payload);
            }
        }
        log::debug!("[socketio] workspace_changed bridge stopped");
    });

    // 6. Memory sync stage + tree-build progress → broadcast to all clients
    //    so the UI can show real-time progress bars and refresh the graph.
    tokio::spawn(async move {
        let bus = {
            const RETRY_INTERVAL_MS: u64 = 250;
            const MAX_WAIT_SECS: u64 = 30;
            let max_attempts = (MAX_WAIT_SECS * 1000) / RETRY_INTERVAL_MS;
            let mut attempts: u64 = 0;
            loop {
                if let Some(bus) = crate::core_host::core::bus::BUS.get() {
                    break bus;
                }
                attempts += 1;
                if attempts > max_attempts {
                    log::warn!(
                        "[socketio] event_bus not initialised after {}s — memory_sync bridge giving up",
                        MAX_WAIT_SECS
                    );
                    return;
                }
                tokio::time::sleep(std::time::Duration::from_millis(RETRY_INTERVAL_MS)).await;
            }
        };
        let mut rx = bus.receiver();
        loop {
            let Some(event) = rx.recv().await else {
                break;
            };
            match event {
                // Live per-step progress of an in-flight flow run (issue G2).
                // Best-effort: the durable `flow_runs` row is the source of
                // truth and the Workflows UI keeps a 2s poller as fallback, so
                // a dropped event here (broadcast lag) only delays the live
                // update, never corrupts run history.
                crate::core_host::core::events::DomainEvent::FlowRunProgress {
                    run_id,
                    node_id,
                    status,
                } => {
                    let payload = serde_json::json!({
                        "run_id": run_id,
                        "node_id": node_id,
                        "status": status,
                    });
                    log::debug!(
                        "[socketio] broadcast flow_run_progress run_id={} node_id={} status={}",
                        run_id,
                        node_id,
                        status
                    );
                    let _ = io_memory_sync.emit("flow:run_progress", &payload);
                    let _ = io_memory_sync.emit("flow_run_progress", &payload);
                }
                // A `flow_runs` row was just persisted, before execution begins
                // (issue B35, runs-rail live refresh). Broadcast so an open
                // Workflows canvas/sidebar can show "Running" immediately
                // instead of waiting for the blocking `flows_run` RPC to
                // resolve or the first `FlowRunProgress` step. Best-effort,
                // same rationale as `flow:run_progress` above.
                crate::core_host::core::events::DomainEvent::FlowRunStarted { flow_id, run_id } => {
                    let payload = serde_json::json!({
                        "flow_id": flow_id,
                        "run_id": run_id,
                    });
                    log::debug!(
                        "[socketio] broadcast flow_run_started flow_id={} run_id={}",
                        flow_id,
                        run_id
                    );
                    let _ = io_memory_sync.emit("flow:run_started", &payload);
                    let _ = io_memory_sync.emit("flow_run_started", &payload);
                }
                // The terminal companion to `FlowRunStarted` above (issue B35
                // follow-up). Published once `flows::ops::finish_flow_run_row`
                // persists the settled `flow_runs` row, so an open Workflows
                // canvas/sidebar can flip a run to Completed/Failed live
                // instead of relying on a poll to notice. Best-effort, same
                // rationale as the other `flow:*` bridges.
                crate::core_host::core::events::DomainEvent::FlowRunFinished {
                    flow_id,
                    run_id,
                    status,
                } => {
                    let payload = serde_json::json!({
                        "flow_id": flow_id,
                        "run_id": run_id,
                        "status": status,
                    });
                    log::debug!(
                        "[socketio] broadcast flow_run_finished flow_id={} run_id={} status={}",
                        flow_id,
                        run_id,
                        status
                    );
                    let _ = io_memory_sync.emit("flow:run_finished", &payload);
                    let _ = io_memory_sync.emit("flow_run_finished", &payload);
                }
                // A saved flow's definition changed (create/update/delete/
                // enable). Broadcast so an open Workflows list/canvas refetches
                // — most importantly, so an agent `save_workflow` becomes
                // visible in a canvas the user has open (audit F6). Best-effort;
                // the UI's refetch-on-focus is the backstop.
                crate::core_host::core::events::DomainEvent::FlowChanged {
                    flow_id,
                    kind,
                    actor,
                } => {
                    let payload = serde_json::json!({
                        "flow_id": flow_id,
                        "kind": kind,
                        "actor": actor,
                    });
                    log::debug!(
                        "[socketio] broadcast flow_changed flow_id={} kind={} actor={}",
                        flow_id,
                        kind,
                        actor
                    );
                    let _ = io_memory_sync.emit("flow:changed", &payload);
                    let _ = io_memory_sync.emit("flow_changed", &payload);
                }
                // A Workflow-origin tool call parked in the `ApprovalGate`
                // (flow-approval-surface, PR2/PR3). Broadcast — not
                // room-scoped like `ApprovalRequested`'s `approval_request`
                // bridge — because a flow run has no chat thread/client to
                // target; the Workflows UI listens process-wide and filters
                // by `flow_id`/`run_id` client-side.
                crate::core_host::core::events::DomainEvent::FlowApprovalRequested {
                    request_id,
                    flow_id,
                    run_id,
                    tool_name,
                    summary,
                    agent_id: _,
                } => {
                    let payload = serde_json::json!({
                        "request_id": request_id,
                        "flow_id": flow_id,
                        "run_id": run_id,
                        "tool_name": tool_name,
                        "summary": summary,
                    });
                    log::info!(
                        "[socketio] broadcast flow_approval_request request_id={} flow_id={} run_id={} tool={}",
                        request_id,
                        flow_id,
                        run_id,
                        tool_name
                    );
                    let _ = io_memory_sync.emit("flow_approval_request", &payload);
                }
                _ => {}
            }
        }
        log::debug!("[socketio] memory_sync bridge stopped");
    });

    // 8. Channel listener health → broadcast `channel:connection-updated` to
    //     all clients so the Messaging tab reflects the *live* connection state
    //     instead of a stale, credential-presence-only "Connected" (issue
    //     #3712). The supervised listener publishes `ChannelConnected` when it
    //     (re)enters its recv loop and `ChannelDisconnected { reason }` when it
    //     errors/exits. Only listener-backed channels (telegram/discord
    //     `bot_token`) fire these, so we map them to the `bot_token` auth mode —
    //     the frontend `normalizeChannelConnectionUpdatePayload` drops any
    //     channel/mode it doesn't recognise.
    tokio::spawn(async move {
        let bus = {
            const RETRY_INTERVAL_MS: u64 = 250;
            const MAX_WAIT_SECS: u64 = 30;
            let max_attempts = (MAX_WAIT_SECS * 1000) / RETRY_INTERVAL_MS;
            let mut attempts: u64 = 0;
            loop {
                if let Some(bus) = crate::core_host::core::bus::BUS.get() {
                    break bus;
                }
                attempts += 1;
                if attempts > max_attempts {
                    log::warn!(
                        "[socketio] event_bus not initialised after {}s — channel_status bridge giving up",
                        MAX_WAIT_SECS
                    );
                    return;
                }
                tokio::time::sleep(std::time::Duration::from_millis(RETRY_INTERVAL_MS)).await;
            }
        };
        let mut rx = bus.receiver();
        loop {
            let Some(event) = rx.recv().await else {
                break;
            };
            let payload = match event {
                crate::core_host::core::events::DomainEvent::ChannelConnected { channel } => {
                    log::debug!(
                        "[socketio] broadcast channel:connection-updated {channel} -> connected"
                    );
                    Some(channel_connection_update_payload(
                        &channel,
                        "connected",
                        None,
                    ))
                }
                crate::core_host::core::events::DomainEvent::ChannelDisconnected {
                    channel,
                    reason,
                } => {
                    log::debug!(
                        "[socketio] broadcast channel:connection-updated {channel} -> error reason_len={}",
                        reason.len()
                    );
                    Some(channel_connection_update_payload(
                        &channel,
                        "error",
                        Some(&reason),
                    ))
                }
                _ => None,
            };
            if let Some(payload) = payload {
                // Emit both colon and underscore variants for FE compatibility.
                let _ = io_channel_status.emit("channel:connection-updated", &payload);
                let _ = io_channel_status.emit("channel_connection_updated", &payload);
            }
        }
        log::debug!("[socketio] channel_status bridge stopped");
    });
}

/// Build the `channel:connection-updated` payload broadcast when a supervised
/// channel listener changes state (issue #3712). Listener-backed channels are
/// always the `bot_token` auth mode (the only mode that materialises a runtime
/// listener for telegram/discord); `last_error` carries the disconnect reason.
/// Matches the shape consumed by the frontend
/// `normalizeChannelConnectionUpdatePayload`.
pub(crate) fn channel_connection_update_payload(
    channel: &str,
    status: &str,
    last_error: Option<&str>,
) -> serde_json::Value {
    let mut payload = serde_json::json!({
        "channel": channel,
        "auth_mode": "bot_token",
        "status": status,
    });
    if let Some(reason) = last_error {
        payload["last_error"] = serde_json::Value::String(reason.to_string());
    }
    payload
}

/// Join `socket` to `room`, logging the result.
///
/// `socket.join()` returns a `Result` that historically was discarded
/// with `let _ = …`. Silent failure on the `"system"` room in
/// particular makes proactive-message delivery vanish without a trace,
/// so both the happy and error paths are logged with enough context
/// (room name + client id) to diagnose missing welcome messages from
/// logs alone.
///
/// Returns whether the socket is actually in the room. Callers that only log
/// may ignore it; a caller that *tells the client* it joined must not — a
/// client told it is in a room it never joined reads the thread, waits for
/// events that will never be routed to it, and reproduces the invisible-reply
/// bug this room exists to prevent (#6034).
fn join_room_logged(socket: &SocketRef, room: &str, client_id: &str) -> bool {
    match socket.join(room.to_string()) {
        Ok(()) => {
            log::debug!("[socketio] joined room '{room}' for client {client_id}");
            true
        }
        Err(e) => {
            log::warn!("[socketio] failed to join room '{room}' for client {client_id}: {e}");
            false
        }
    }
}

fn emit_web_channel_event(io: &SocketIo, event: ScopedWebEvent) {
    let name = event.event_name();
    // Deliver to the initiating client's own room AND the per-thread room. The
    // thread room lets a socket that reconnected with a new client_id (after
    // re-subscribing via `thread:subscribe`) keep receiving an in-flight turn's
    // stream.
    //
    // ⚠️ socketioxide (0.15.2) does NOT de-duplicate a socket present in
    // multiple target rooms: `LocalAdapter::apply_opts` flattens each room's
    // sid-set and collects WITHOUT a dedup pass, so `io.to([a, b]).emit()`
    // delivers TWICE to a socket in both `a` and `b`. The initiating client is
    // in both its `client_id` room and the `thread:<id>` room it subscribed to
    // → every streamed frame doubled ("double thinking"). So we emit to the
    // `client_id` room, then to the thread room EXCEPT the `client_id` room —
    // each socket is reached exactly once regardless of room overlap.
    // "system" broadcasts and events without a thread_id keep single-room delivery.
    let context = event.context();
    let primary = context.client_id.clone();
    let thread_room = (context.client_id != "system" && !context.thread_id.is_empty())
        .then(|| format!("thread:{}", context.thread_id));
    if let Ok(payload) = serde_json::to_value(event) {
        log::debug!(
            "[socketio] send event={} primary={} thread_room={:?} thread_id={} request_id={}",
            name,
            primary,
            thread_room,
            payload
                .get("thread_id")
                .and_then(|v| v.as_str())
                .unwrap_or_default(),
            payload
                .get("request_id")
                .and_then(|v| v.as_str())
                .unwrap_or_default()
        );
        // Primary: the client_id room.
        let _ = io.to(primary.clone()).emit(name, &payload);
        if let Some(alias) = event_alias(name) {
            let _ = io.to(primary.clone()).emit(alias, &payload);
        }
        // Thread room minus the client_id room (dedup — see note above).
        if let Some(tr) = thread_room {
            let _ = io
                .to(tr.clone())
                .except(primary.clone())
                .emit(name, &payload);
            if let Some(alias) = event_alias(name) {
                let _ = io
                    .to(tr.clone())
                    .except(primary.clone())
                    .emit(alias, &payload);
            }
        }
    }
}

/// Events that stream once per token (their payloads concatenate into the final
/// text / thinking / tool-args). Emitting the legacy `:`-delimited alias for
/// these doubles every frame on the wire — the "double thinking-token
/// streaming" bug — and no client subscribes to the colon variant, so the alias
/// is suppressed for exactly these. Enumerated explicitly rather than matched by
/// a `*_delta` suffix, so a future *discrete* event whose name happens to end in
/// `_delta` still gets its compat alias instead of being silently dropped.
const STREAMING_DELTA_EVENTS: &[&str] = &["text_delta", "thinking_delta", "tool_args_delta"];

fn event_alias(name: &str) -> Option<String> {
    // Match against the canonical underscore form after stripping a `subagent_`
    // prefix (subagent streaming mirrors the parent's deltas), so `text_delta`,
    // `text:delta`, and `subagent_text_delta` all resolve to a listed event.
    // Lower-frequency discrete events keep the compat alias.
    let normalized = name.replace(':', "_");
    let base = normalized.strip_prefix("subagent_").unwrap_or(&normalized);
    if STREAMING_DELTA_EVENTS.contains(&base) {
        return None;
    }
    if name.contains('_') {
        return Some(name.replace('_', ":"));
    }
    if name.contains(':') {
        return Some(name.replace(':', "_"));
    }
    None
}

/// Re-send the approval parked on `thread_id`, if any, to the socket that just
/// joined that thread's room.
///
/// An approval is durable server-side state — the gate holds the parked call
/// and a `pending_approvals` row — but it reaches the UI as ONE fire-and-forget
/// emit from [`emit_web_channel_event`]. That emit can miss with no error and
/// no trace: `io.to(room).emit()` on a room whose only member has gone is a
/// silent no-op, there is no disconnect handler here so the core never learns a
/// client died, a socket that reconnects lands in the thread room only for
/// events emitted *after* it joins, and the bridge drops frames wholesale on
/// broadcast lag. Any one of those leaves the turn parked forever with no card
/// on screen and no way for the user to act.
///
/// `thread:subscribe` is the one signal that says "this socket is now watching
/// this thread", which makes it the place to reconcile the two. Replaying is
/// safe to repeat: the client keys the card by `request_id` and a decided
/// request is no longer parked, so a socket that already has the card just
/// re-renders the same one.
///
/// Every park on the thread is replayed, oldest first: several async
/// sub-agents can each be waiting on the same parent thread, and replaying
/// only the newest left the others unanswerable until they expired.
fn replay_parked_approval(socket: &SocketRef, thread_id: &str) {
    let Some(gate) = crate::core_host::security::approval::ApprovalGate::try_global() else {
        return;
    };
    let client_id = socket.id.to_string();
    for row in gate.parked_requests_for_thread(thread_id) {
        let expires_at = row.expires_at.map(|t| t.to_rfc3339());
        let mut event = crate::core_host::web_chat::approval_request_event(
            &row.request_id,
            &row.tool_name,
            &row.action_summary,
            &row.args_redacted,
            thread_id,
            &client_id,
            row.tool_call_id.as_deref(),
            expires_at.as_deref(),
            gate.request_is_detached(&row.request_id),
        );
        // Replay is a fresh emit to a newly-joined socket, not a resend of the
        // original event, so stamp `ts` with "now" (same clock as
        // `publish_web_channel_event`) rather than leaving it unset.
        stamp_replay_timestamp(&mut event);
        let Ok(payload) = serde_json::to_value(&event) else {
            continue;
        };
        log::info!(
            "[socketio] replaying parked approval_request to joining socket client_id={client_id} thread_id={thread_id} request_id={} tool={}",
            row.request_id,
            row.tool_name
        );
        emit_with_aliases(socket, "approval_request", &payload);
    }
}

/// Re-send the plan review parked on `thread_id`, if any, to the socket that
/// just joined that thread's room. Mirrors [`replay_parked_approval`] — a
/// plan review is a live, in-memory park (no SQLite row), but it reaches the
/// UI the same fire-and-forget way, so the same reconciliation applies.
fn replay_parked_plan_review(socket: &SocketRef, thread_id: &str) {
    let Some(tenant) = socket.extensions.get::<SocketTenant>() else {
        return;
    };
    let Some(row) =
        crate::core_host::agent::plan_review::parked_review_for_socket(&tenant.0, thread_id)
    else {
        return;
    };
    let client_id = socket.id.to_string();
    let mut event = crate::core_host::web_chat::plan_review_request_event(
        &row.request_id,
        &row.summary,
        &row.steps,
        thread_id,
        &client_id,
        row.tool_call_id.as_deref(),
        Some(row.expires_at.as_str()),
    );
    stamp_replay_timestamp(&mut event);
    let Ok(payload) = serde_json::to_value(&event) else {
        return;
    };
    log::info!(
        "[socketio] replaying parked plan_review_request to joining socket client_id={client_id} thread_id={thread_id} request_id={}",
        row.request_id
    );
    emit_with_aliases(socket, "plan_review_request", &payload);
}

fn emit_with_aliases(socket: &SocketRef, name: &str, payload: &serde_json::Value) {
    let _ = socket.emit(name, payload);
    if let Some(alias) = event_alias(name) {
        let _ = socket.emit(alias, payload);
    }
}

fn stamp_replay_timestamp(event: &mut crate::core_host::web_chat::WebChannelEvent) {
    event.context_mut().ts = Some(crate::core_host::web_chat::unix_epoch_ms());
}

// Every test here names a gated fn (`channel_connection_update_payload`,
// `event_alias`, `origin_is_allowed`), so the module gates in lockstep (#5048).
#[cfg(test)]
#[path = "socketio_tests.rs"]
mod tests;