Struct SessionRegistry 

pub struct SessionRegistry { /* private fields */ }

Manages active sessions.

Locking design (lock C)

Uses tokio::sync::Mutex because feed_response holds the lock while calling Session::feed_one() (which itself acquires the per-session std::sync::Mutex<SessionStatus>, lock A). The lock ordering invariant is always C → A — no code path acquires A then C, so deadlock is structurally impossible.

tokio::sync::Mutex is chosen here (rather than std::sync::Mutex) because feed_response must take the session out of the map for the async wait_event() call. The two-phase pattern (lock → remove → unlock → await → lock → reinsert) requires an async-aware mutex to avoid holding the lock across the wait_event().await.

Contention

list_snapshots() (from alc_status) holds lock C while iterating all sessions. During this time, feed_response for any session is blocked. Given that snapshot iteration is O(n) with n = active sessions (typically 1–3) and each snapshot takes microseconds, this is acceptable. If session count grows significantly, consider switching to a concurrent map or per-session locks.

Interaction with lock A

Session::snapshot() (called under lock C in list_snapshots) acquires lock A via ExecutionMetrics::snapshot(). This is safe:

• Lock order: C → A (consistent with feed_response)
• Lock A hold time: microseconds (JSON field reads)
• Lock A is per-session (no cross-session contention)

Implementations

impl SessionRegistry

pub fn new() -> Self

pub async fn start_execution( &self, session: Session, ) -> Result<(String, FeedResult), SessionError>

Start execution and wait for first event (pause or completion).

pub async fn feed_response( &self, session_id: &str, query_id: &QueryId, response: String, usage: Option<&TokenUsage>, ) -> Result<FeedResult, SessionError>

Feed one response to a paused session by query_id.

If this completes all pending queries, the session resumes and returns the next event (Paused or Finished). If queries remain, returns Accepted { remaining }.

pub async fn resolve_sole_pending_id( &self, session_id: &str, ) -> Result<QueryId, SessionError>

Resolve the sole pending query ID for a session.

When alc_continue is called without an explicit query_id, this method checks if exactly one query is pending and returns its ID. Returns an error if zero or multiple queries are pending.

pub async fn list_snapshots(&self) -> HashMap<String, Value>

Snapshot all active sessions for external observation (alc_status).

Returns a map of session_id → snapshot JSON. Only includes sessions currently held in the registry (i.e. paused, awaiting responses). Sessions that have completed are already removed from the registry.

pub fn spawn_gc_task(&self, ttl: Duration)

Spawn a background GC task that reaps sessions idle longer than ttl.

The task runs every 60 seconds. When the process exits, the task is naturally terminated. No JoinHandle is retained — process exit is sufficient for cleanup in MCP server deployments.

Trait Implementations

impl Default for SessionRegistry

fn default() -> Self

Returns the “default value” for a type.