Module session 

Per-client session state and lifecycle.

Each WebSocket connection (and each MCP client) is wrapped in a Session managed by a SessionManager. Sessions are isolated: open packs in one session aren’t visible from another, and each one owns a dedicated background thread (see crate::background_thread) that processes its commands serially. The one exception is application settings, which live in crate::settings::SETTINGS, a single store shared by every session in this process.

Lifecycle

1. Create. A new session gets a unique SessionId from the manager plus a fresh background thread spawned on the tokio runtime.
2. Connect / disconnect. Clients increment Session::connect on attach and Session::disconnect on detach. The connection count is what the timeout logic watches.
3. Reconnect. A client can pass its previous session_id back on the next WebSocket handshake to adopt the same session and recover its in-memory state. See SessionManager::get_or_create_session.
4. Timeout. When the connection count drops to zero, the session enters a DEFAULT_SESSION_TIMEOUT_SECS-long grace period. Reconnects cancel the timeout; otherwise the cleanup task removes the session and its background thread exits.
5. Empty manager → process exit. When the last session is removed the server process terminates, so no orphaned backend lingers in the background.

MCP sessions

MCP clients have no disconnect signal the server can rely on: the MCP transport keeps a session registered until the client sends an HTTP DELETE, which many clients never send. Sessions created for MCP clients (SessionManager::create_mcp_session) are therefore never counted as connected; instead, the periodic cleanup task reaps them once no command has been sent through them for DEFAULT_SESSION_TIMEOUT_SECS.

Structs

ManagedSession 🔒

Internal state for a managed session.

Session

A session represents a single client’s connection state.

SessionManager

Manages all active sessions.

Constants

DEFAULT_SESSION_TIMEOUT_SECS

Default session timeout in seconds (5 minutes).

SESSION_SENDER_ERROR

Error messages for session communication.

Functions

recv_response

Helper function to receive a response from a session.

Type Aliases

SessionId

Unique identifier for a session.