Skip to content

An agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.

Rust
46.2 KB
Raw Blame
//! Durable SDK session routing and turn lifecycle operations.

pub mod events;
pub mod reconciliation;
pub mod terminal_scope;

pub use events::{SessionEvent, SessionEventType};
pub use reconciliation::{
    InvocationOutcome, InvocationReconciliationStore, InvocationRecord, InvocationStatus,
};
pub use terminal_scope::{TerminalScopeRecord, TerminalScopeStore};

use std::collections::{BTreeMap, HashMap};
use std::fmt::{Debug, Formatter};
use std::panic::{catch_unwind, AssertUnwindSafe};
use std::sync::{Arc, Mutex, MutexGuard};
use std::thread;
use std::time::{SystemTime, UNIX_EPOCH};

use runtime::{
    ApiClient, ConversationEvent, ConversationRuntime, Session, SessionStore, ToolExecutor,
    TurnControlSignal,
};
use serde::{Deserialize, Serialize};
use serde_json::{json, Map, Value};
use tokio::sync::{mpsc, watch};
use uuid::Uuid;

use crate::error::{SdkError, SdkResult};
use crate::frame::{FrameType, SdkFrame};

const DEFAULT_PAGE_SIZE: usize = 20;
const MAX_PAGE_SIZE: usize = 100;
const MAX_SESSION_ID_BYTES: usize = 128;
const MAX_CORRELATION_KEY_BYTES: usize = 512;

/// Result returned by one session turn implementation.
pub enum SessionRunResult {
    Completed(Session),
    Aborted(Session),
    Failed { session: Session, message: String },
}

/// Pluggable synchronous turn driver used by [`SessionRouter`].
pub trait SessionTurnRunner: Send + Sync + 'static {
    fn run(
        &self,
        session: Session,
        prompt: String,
        control: TurnControlSignal,
        event_callback: Arc<dyn Fn(ConversationEvent) + Send + Sync>,
    ) -> SessionRunResult;
}

/// Bridges a runtime conversation into the SDK session router.
pub struct RuntimeSessionRunner<C, T> {
    build_runtime: Arc<dyn Fn(Session) -> ConversationRuntime<C, T> + Send + Sync>,
    marker: std::marker::PhantomData<fn() -> (C, T)>,
}

impl<C, T> RuntimeSessionRunner<C, T>
where
    C: ApiClient + 'static,
    T: ToolExecutor + 'static,
{
    /// Construct a runner from a factory that supplies the API and tool clients.
    pub fn new<F>(build_runtime: F) -> Self
    where
        F: Fn(Session) -> ConversationRuntime<C, T> + Send + Sync + 'static,
    {
        Self {
            build_runtime: Arc::new(build_runtime),
            marker: std::marker::PhantomData,
        }
    }
}

impl<C, T> SessionTurnRunner for RuntimeSessionRunner<C, T>
where
    C: ApiClient + 'static,
    T: ToolExecutor + 'static,
{
    fn run(
        &self,
        session: Session,
        mut prompt: String,
        control: TurnControlSignal,
        event_callback: Arc<dyn Fn(ConversationEvent) + Send + Sync>,
    ) -> SessionRunResult {
        let mut runtime = (self.build_runtime)(session)
            .with_turn_control_signal(control.clone())
            .with_event_callback(event_callback);

        loop {
            match runtime.run_turn(prompt, None) {
                Ok(summary) if summary.interrupted || control.is_aborted() => {
                    return SessionRunResult::Aborted(runtime.into_session());
                }
                Ok(_) => match control.finish_or_take_steer() {
                    Some(steer) => prompt = steer,
                    None => return SessionRunResult::Completed(runtime.into_session()),
                },
                Err(error) => {
                    control.close();
                    return SessionRunResult::Failed {
                        session: runtime.into_session(),
                        message: error.to_string(),
                    };
                }
            }
        }
    }
}

/// One paginated row returned by `turn.list`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SessionSummary {
    pub session_id: String,
    pub created_at_ms: u64,
    pub updated_at_ms: u64,
    pub message_count: usize,
}

/// Page of persisted sessions. `next_cursor` is an opaque decimal offset.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SessionPage {
    pub sessions: Vec<SessionSummary>,
    pub next_cursor: Option<String>,
}

/// A started invocation and its ordered event stream.
pub struct SessionInvocation {
    pub session_id: String,
    pub invocation_id: String,
    pub events: SessionEventStream,
}

impl Debug for SessionInvocation {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("SessionInvocation")
            .field("session_id", &self.session_id)
            .field("invocation_id", &self.invocation_id)
            .finish_non_exhaustive()
    }
}

/// Receiver for lifecycle events emitted by an invocation.
pub struct SessionEventStream {
    receiver: mpsc::UnboundedReceiver<SessionEvent>,
}

impl Debug for SessionEventStream {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("SessionEventStream")
            .finish_non_exhaustive()
    }
}

impl SessionEventStream {
    /// Receive the next lifecycle event, returning `None` after the stream closes.
    pub async fn recv(&mut self) -> Option<SessionEvent> {
        self.receiver.recv().await
    }
}

/// Result of dispatching one SDK broker request.
pub struct SessionDispatch {
    pub response: SdkFrame,
    pub events: Option<SessionEventStream>,
}

impl Debug for SessionDispatch {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("SessionDispatch")
            .field("response", &self.response)
            .field("has_events", &self.events.is_some())
            .finish()
    }
}

#[derive(Clone)]
pub struct SessionRouter {
    inner: Arc<SessionRouterInner>,
}

struct SessionRouterInner {
    store: SessionStore,
    runner: Arc<dyn SessionTurnRunner>,
    reconciliation: InvocationReconciliationStore,
    terminal_scopes: TerminalScopeStore,
    reconciliation_lock: Mutex<()>,
    active: Mutex<HashMap<String, ActiveInvocation>>,
}

#[derive(Clone)]
struct ActiveInvocation {
    invocation_id: String,
    correlation_key: Option<String>,
    control: TurnControlSignal,
    event_publisher: Arc<SessionEventPublisher>,
    done: watch::Receiver<bool>,
}

struct SessionEventPublisher {
    session_id: String,
    invocation_id: String,
    sequence: std::sync::atomic::AtomicU64,
    publication_lock: Mutex<()>,
    sender: mpsc::UnboundedSender<SessionEvent>,
}

impl SessionEventPublisher {
    fn new(
        session_id: String,
        invocation_id: String,
        sender: mpsc::UnboundedSender<SessionEvent>,
    ) -> Self {
        Self {
            session_id,
            invocation_id,
            sequence: std::sync::atomic::AtomicU64::new(0),
            publication_lock: Mutex::new(()),
            sender,
        }
    }

    fn lock(&self) -> MutexGuard<'_, ()> {
        self.publication_lock
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner)
    }

    fn build_locked(
        &self,
        event_type: SessionEventType,
        payload: Value,
        durable: bool,
    ) -> SessionEvent {
        let sequence = self
            .sequence
            .fetch_add(1, std::sync::atomic::Ordering::SeqCst)
            .saturating_add(1);
        SessionEvent {
            event_id: format!("{}:{sequence}", self.invocation_id),
            event_type,
            session_id: self.session_id.clone(),
            invocation_id: self.invocation_id.clone(),
            sequence,
            timestamp_ms: now_ms(),
            durable,
            payload,
        }
    }

    fn publish(&self, event_type: SessionEventType, payload: Value, durable: bool) -> SessionEvent {
        let _guard = self.lock();
        self.publish_locked(event_type, payload, durable)
    }

    fn publish_locked(
        &self,
        event_type: SessionEventType,
        payload: Value,
        durable: bool,
    ) -> SessionEvent {
        let event = self.build_locked(event_type, payload, durable);
        let _ = self.sender.send(event.clone());
        event
    }

    fn publish_steer(&self, control: &TurnControlSignal, prompt: &str) -> bool {
        let _guard = self.lock();
        if !control.steer(prompt.to_string()) {
            return false;
        }
        self.publish_locked(
            SessionEventType::TurnSteered,
            json!({ "prompt": prompt }),
            false,
        );
        true
    }

    fn publish_runtime_event(&self, event: ConversationEvent) {
        let (event_type, payload) = match event {
            ConversationEvent::AgentBegin { session_id: _ } => {
                (SessionEventType::AgentBegin, json!({}))
            }
            ConversationEvent::ToolUse {
                tool_use_id,
                tool_name,
                input,
            } => (
                SessionEventType::ToolUse,
                json!({
                    "toolUseId": tool_use_id,
                    "toolName": tool_name,
                    "input": input,
                }),
            ),
            ConversationEvent::ToolResult {
                tool_use_id,
                tool_name,
                output,
                is_error,
            } => (
                SessionEventType::ToolResult,
                json!({
                    "toolUseId": tool_use_id,
                    "toolName": tool_name,
                    "output": output,
                    "isError": is_error,
                }),
            ),
            ConversationEvent::AgentEnd {
                session_id: _,
                interrupted,
                output,
            } => {
                let mut payload = json!({ "interrupted": interrupted });
                if let Some(output) = output {
                    payload["output"] = Value::String(output);
                }
                (SessionEventType::AgentEnd, payload)
            }
        };
        self.publish(event_type, payload, false);
    }
}

impl SessionRouter {
    /// Create a router backed by the supplied durable session store.
    ///
    /// Interrupted invocations left by an earlier process are moved to the
    /// uncertain state so clients can reconcile them against their correlation key.
    pub fn new(store: SessionStore, runner: Arc<dyn SessionTurnRunner>) -> SdkResult<Self> {
        let sdk_root = store.sessions_dir().join("sdk");
        let reconciliation = InvocationReconciliationStore::new(sdk_root.join("reconciliation"));
        let terminal_scopes = TerminalScopeStore::new(sdk_root.join("terminal-scopes"));
        reconciliation.reconcile_unfinished()?;
        recover_terminal_scopes(&reconciliation, &terminal_scopes)?;
        recover_pending_terminal_outcomes(&reconciliation, &terminal_scopes)?;
        Ok(Self {
            inner: Arc::new(SessionRouterInner {
                store,
                runner,
                reconciliation,
                terminal_scopes,
                reconciliation_lock: Mutex::new(()),
                active: Mutex::new(HashMap::new()),
            }),
        })
    }

    /// Create and persist an empty session, optionally assigning its model and correlation scope.
    pub fn create_session(
        &self,
        model: Option<&str>,
        correlation_key: Option<&str>,
    ) -> SdkResult<Session> {
        validate_optional_correlation_key(correlation_key)?;
        let model = model.map(str::trim).filter(|value| !value.is_empty());
        if model.is_some_and(|value| value.len() > 256) {
            return Err(SdkError::invalid_input("model name exceeds 256 bytes"));
        }

        let mut session =
            Session::new().with_workspace_root(self.inner.store.workspace_root().to_path_buf());
        session.model = model.map(str::to_string);
        let handle = self.inner.store.create_handle(&session.session_id);
        session = session.with_persistence_path(handle.path.clone());
        session
            .save_to_path(&handle.path)
            .map_err(|error| SdkError::internal(format!("could not persist session: {error}")))?;
        if let Some(key) = correlation_key {
            let _reconciliation_guard = self
                .inner
                .reconciliation_lock
                .lock()
                .unwrap_or_else(std::sync::PoisonError::into_inner);
            self.inner.terminal_scopes.set(key, &session.session_id)?;
        }
        Ok(session)
    }

    /// Load a session by its durable ID, rejecting aliases and path-like IDs.
    pub fn get_session(&self, session_id: &str) -> SdkResult<Session> {
        validate_session_id(session_id)?;
        let path = self
            .inner
            .store
            .resolve_managed_path(session_id)
            .map_err(|error| SdkError::not_found(error.to_string()))?;
        let session = Session::load_from_path(&path)
            .map_err(|error| SdkError::internal(format!("could not load session: {error}")))?;
        if session.session_id != session_id {
            return Err(SdkError::not_found(format!(
                "session `{session_id}` does not match the requested ID"
            )));
        }
        Ok(session)
    }

    /// Resolve the most recently recorded session for a correlation key.
    pub fn session_for_correlation_key(&self, correlation_key: &str) -> SdkResult<Option<String>> {
        validate_correlation_key(correlation_key)?;
        let _reconciliation_guard = self
            .inner
            .reconciliation_lock
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        recover_pending_terminal_outcomes(&self.inner.reconciliation, &self.inner.terminal_scopes)?;
        let active_matches = {
            let active = self
                .inner
                .active
                .lock()
                .unwrap_or_else(std::sync::PoisonError::into_inner);
            active
                .iter()
                .filter(|(_, invocation)| {
                    invocation.correlation_key.as_deref() == Some(correlation_key)
                })
                .map(|(session_id, invocation)| {
                    (session_id.clone(), invocation.invocation_id.clone())
                })
                .collect::<Vec<_>>()
        };
        if active_matches.len() > 1 {
            return Err(SdkError::conflict(format!(
                "correlation key '{correlation_key}' has multiple active sessions"
            )));
        }

        let has_unfinished_invocation = self
            .inner
            .reconciliation
            .list_by_correlation_key(correlation_key)?
            .iter()
            .any(|record| {
                record.status != InvocationStatus::Terminal
                    && active_matches
                        .first()
                        .is_none_or(|(_, active_id)| record.invocation_id != *active_id)
            });
        if has_unfinished_invocation {
            return Err(SdkError::unavailable(format!(
                "correlation key '{correlation_key}' has an invocation awaiting reconciliation"
            )));
        }
        if let Some((session_id, _)) = active_matches.first() {
            return Ok(Some(session_id.clone()));
        }
        let scope = self.inner.terminal_scopes.get(correlation_key)?;
        Ok(scope.map(|scope| scope.session_id))
    }

    /// Start a prompt and return immediately with an ordered event receiver.
    pub fn prompt(
        &self,
        session_id: &str,
        prompt: impl Into<String>,
        correlation_key: Option<&str>,
    ) -> SdkResult<SessionInvocation> {
        let prompt = prompt.into();
        validate_session_id(session_id)?;
        validate_prompt(&prompt)?;
        validate_optional_correlation_key(correlation_key)?;

        let mut active = self
            .inner
            .active
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        if active.contains_key(session_id) {
            return Err(SdkError::conflict(format!(
                "session `{session_id}` already has an active invocation"
            )));
        }
        // Load after reserving the session slot. Loading before this lock lets a
        // waiting prompt retain a stale snapshot and overwrite the prior turn.
        let session = self.get_session(session_id)?;

        let invocation_id = Uuid::new_v4().to_string();
        let created_at_ms = now_ms();
        let record = InvocationRecord {
            invocation_id: invocation_id.clone(),
            session_id: session_id.to_string(),
            correlation_key: correlation_key.map(str::to_string),
            status: InvocationStatus::Accepted,
            accepted_at_ms: created_at_ms,
            updated_at_ms: created_at_ms,
            outcome: None,
            uncertainty_reason: None,
            terminal_event: None,
            terminal_scope_revision: None,
        };
        self.inner.reconciliation.insert(record)?;

        let (event_tx, event_rx) = mpsc::unbounded_channel();
        let publisher = Arc::new(SessionEventPublisher::new(
            session_id.to_string(),
            invocation_id.clone(),
            event_tx,
        ));
        let control = TurnControlSignal::new();
        let (done_tx, done_rx) = watch::channel(false);
        active.insert(
            session_id.to_string(),
            ActiveInvocation {
                invocation_id: invocation_id.clone(),
                correlation_key: correlation_key.map(str::to_string),
                control: control.clone(),
                event_publisher: publisher.clone(),
                done: done_rx,
            },
        );
        drop(active);

        publisher.publish(
            SessionEventType::TurnAccepted,
            json!({ "correlationKey": correlation_key }),
            false,
        );

        let inner = Arc::clone(&self.inner);
        let worker_session_id = session_id.to_string();
        let worker_invocation_id = invocation_id.clone();
        let worker_publisher = publisher.clone();
        let worker_control = control.clone();
        let worker_correlation_key = correlation_key.map(str::to_string);
        let worker_session = session.clone();
        let worker_done_tx = done_tx.clone();
        let worker = thread::Builder::new()
            .name(format!("sdk-session-{}", &invocation_id[..8]))
            .spawn(move || {
                if let Err(error) = inner.reconciliation.mark_running(&worker_invocation_id) {
                    finish_uncertain(
                        &inner,
                        &worker_invocation_id,
                        &worker_control,
                        &worker_publisher,
                        &error.to_string(),
                    );
                    remove_active(&inner, &worker_session_id, &worker_invocation_id);
                    let _ = worker_done_tx.send(true);
                    return;
                }
                let event_publisher = worker_publisher.clone();
                let callback: Arc<dyn Fn(ConversationEvent) + Send + Sync> =
                    Arc::new(move |event| event_publisher.publish_runtime_event(event));
                let result = catch_unwind(AssertUnwindSafe(|| {
                    inner
                        .runner
                        .run(worker_session, prompt, worker_control.clone(), callback)
                }));
                match result {
                    Ok(run_result) => finish_invocation(
                        &inner,
                        &worker_session_id,
                        &worker_invocation_id,
                        worker_correlation_key.as_deref(),
                        &worker_control,
                        &worker_publisher,
                        run_result,
                    ),
                    Err(panic) => {
                        let reason = panic_message(panic);
                        finish_uncertain(
                            &inner,
                            &worker_invocation_id,
                            &worker_control,
                            &worker_publisher,
                            &reason,
                        );
                    }
                }
                remove_active(&inner, &worker_session_id, &worker_invocation_id);
                let _ = worker_done_tx.send(true);
            });

        if let Err(error) = worker {
            let message = format!("could not start session worker: {error}");
            finish_invocation(
                &self.inner,
                session_id,
                &invocation_id,
                correlation_key,
                &control,
                &publisher,
                SessionRunResult::Failed { session, message },
            );
            remove_active(&self.inner, session_id, &invocation_id);
            let _ = done_tx.send(true);
        }

        Ok(SessionInvocation {
            session_id: session_id.to_string(),
            invocation_id,
            events: SessionEventStream { receiver: event_rx },
        })
    }

    /// Queue a steering prompt for the active invocation of a session.
    pub fn steer(
        &self,
        session_id: &str,
        invocation_id: &str,
        override_prompt: impl Into<String>,
    ) -> SdkResult<()> {
        validate_session_id(session_id)?;
        validate_invocation_id(invocation_id)?;
        let prompt = override_prompt.into();
        validate_prompt(&prompt)?;
        let (control, publisher) = {
            let active = self
                .inner
                .active
                .lock()
                .unwrap_or_else(std::sync::PoisonError::into_inner);
            let invocation = active
                .get(session_id)
                .ok_or_else(|| SdkError::not_found("session has no active invocation"))?;
            if invocation.invocation_id != invocation_id {
                return Err(SdkError::not_found(format!(
                    "invocation `{invocation_id}` is not active for session `{session_id}`"
                )));
            }
            (
                invocation.control.clone(),
                Arc::clone(&invocation.event_publisher),
            )
        };
        if !publisher.publish_steer(&control, &prompt) {
            return Err(SdkError::conflict("invocation no longer accepts steering"));
        }
        Ok(())
    }

    /// Abort the current invocation, wait for its durable terminal outcome, then start a new prompt.
    pub async fn abort_and_prompt(
        &self,
        session_id: &str,
        prompt: impl Into<String>,
        correlation_key: Option<&str>,
    ) -> SdkResult<SessionInvocation> {
        validate_session_id(session_id)?;
        let prompt = prompt.into();
        validate_prompt(&prompt)?;
        validate_optional_correlation_key(correlation_key)?;

        let (mut done, inherited_correlation, previous_invocation_id) = {
            let active = self
                .inner
                .active
                .lock()
                .unwrap_or_else(std::sync::PoisonError::into_inner);
            match active.get(session_id) {
                Some(invocation) => {
                    invocation.control.abort();
                    (
                        Some(invocation.done.clone()),
                        invocation.correlation_key.clone(),
                        Some(invocation.invocation_id.clone()),
                    )
                }
                None => (None, None, None),
            }
        };
        if let Some(receiver) = done.as_mut() {
            while !*receiver.borrow() {
                receiver.changed().await.map_err(|_| {
                    SdkError::unavailable("session invocation stopped unexpectedly")
                })?;
            }
        }

        if let Some(invocation_id) = previous_invocation_id {
            let record = self
                .inner
                .reconciliation
                .get(&invocation_id)?
                .ok_or_else(|| SdkError::not_found("aborted invocation record was not found"))?;
            if record.status != InvocationStatus::Terminal {
                return Err(SdkError::unavailable(format!(
                    "invocation `{invocation_id}` has no durable terminal outcome"
                )));
            }
        }

        let effective_correlation = correlation_key
            .map(str::to_string)
            .or(inherited_correlation);
        self.prompt(session_id, prompt, effective_correlation.as_deref())
    }

    /// List persisted sessions using an opaque offset cursor.
    pub fn list(&self, cursor: Option<&str>, limit: Option<usize>) -> SdkResult<SessionPage> {
        let offset = match cursor {
            Some(value) => value.parse::<usize>().map_err(|_| {
                SdkError::invalid_input("cursor must be a non-negative decimal offset")
            })?,
            None => 0,
        };
        let limit = limit.unwrap_or(DEFAULT_PAGE_SIZE);
        if !(1..=MAX_PAGE_SIZE).contains(&limit) {
            return Err(SdkError::invalid_input(format!(
                "limit must be between 1 and {MAX_PAGE_SIZE}"
            )));
        }
        let sessions = self
            .inner
            .store
            .list_sessions()
            .map_err(|error| SdkError::internal(format!("could not list sessions: {error}")))?;
        let total = sessions.len();
        let summaries = sessions
            .into_iter()
            .skip(offset)
            .take(limit)
            .map(|session| SessionSummary {
                session_id: session.id,
                created_at_ms: session.created_at_ms,
                updated_at_ms: session.updated_at_ms,
                message_count: session.message_count,
            })
            .collect::<Vec<_>>();
        let next_offset = offset.saturating_add(summaries.len());
        let next_cursor = (next_offset < total).then(|| next_offset.to_string());
        Ok(SessionPage {
            sessions: summaries,
            next_cursor,
        })
    }

    /// Return a durable invocation record for recovery after a disconnected client.
    pub fn reconcile(&self, invocation_id: &str) -> SdkResult<InvocationRecord> {
        validate_invocation_id(invocation_id)?;
        let _reconciliation_guard = self
            .inner
            .reconciliation_lock
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        recover_pending_terminal_outcomes(&self.inner.reconciliation, &self.inner.terminal_scopes)?;
        self.inner
            .reconciliation
            .get(invocation_id)?
            .ok_or_else(|| {
                SdkError::not_found(format!("invocation `{invocation_id}` was not found"))
            })
    }

    /// Return all invocation outcomes associated with a correlation key in stable ID order.
    pub fn reconcile_by_correlation_key(
        &self,
        correlation_key: &str,
    ) -> SdkResult<Vec<InvocationRecord>> {
        validate_correlation_key(correlation_key)?;
        let _reconciliation_guard = self
            .inner
            .reconciliation_lock
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        recover_pending_terminal_outcomes(&self.inner.reconciliation, &self.inner.terminal_scopes)?;
        self.inner
            .reconciliation
            .list_by_correlation_key(correlation_key)
    }

    /// Dispatch a broker request for `turn.create`, `turn.prompt`, `turn.steer`,
    /// `turn.abort_and_prompt`, or `turn.list`.
    pub async fn dispatch(&self, request: SdkFrame) -> SdkResult<SessionDispatch> {
        if request.frame_type()? != FrameType::BrokerRequest {
            return Err(SdkError::invalid_input(
                "session router requires a broker_request frame",
            ));
        }
        let request_id = request.id()?.ok_or_else(|| {
            SdkError::invalid_input("request frame is missing its correlation ID")
        })?;
        let operation = request
            .operation()
            .ok_or_else(|| SdkError::invalid_input("request frame is missing its operation"))?;
        let input = request.input().unwrap_or_else(|| json!({}));
        let object = input
            .as_object()
            .ok_or_else(|| SdkError::invalid_input("operation input must be a JSON object"))?;

        match operation.as_str() {
            "turn.create" => {
                let correlation_key = optional_string(object, "correlationKey")?;
                let model = optional_string(object, "model")?;
                let initial_prompt = optional_prompt(object, "input")?;
                if let Some(prompt) = initial_prompt.as_deref() {
                    validate_prompt(prompt)?;
                }
                let session = self.create_session(model.as_deref(), correlation_key.as_deref())?;
                if let Some(prompt) = initial_prompt {
                    let invocation =
                        self.prompt(&session.session_id, prompt, correlation_key.as_deref())?;
                    let response = SdkFrame::broker_response_ok(
                        request_id,
                        json!({
                            "sessionId": session.session_id,
                            "invocationId": invocation.invocation_id,
                        }),
                    );
                    Ok(SessionDispatch {
                        response,
                        events: Some(invocation.events),
                    })
                } else {
                    Ok(SessionDispatch {
                        response: SdkFrame::broker_response_ok(
                            request_id,
                            json!({ "sessionId": session.session_id }),
                        ),
                        events: None,
                    })
                }
            }
            "turn.prompt" => {
                let session_id = self.resolve_session_id(object)?;
                let prompt = required_turn_prompt(object)?;
                let correlation_key = optional_string(object, "correlationKey")?;
                let invocation = self.prompt(&session_id, prompt, correlation_key.as_deref())?;
                Ok(SessionDispatch {
                    response: SdkFrame::broker_response_ok(
                        request_id,
                        invocation_result(&invocation),
                    ),
                    events: Some(invocation.events),
                })
            }
            "turn.steer" => {
                let session_id = self.resolve_session_id(object)?;
                let invocation_id = required_string(object, "invocationId")?;
                let prompt = match object.get("override") {
                    Some(value) => prompt_value(value)?,
                    None => required_turn_prompt(object)?,
                };
                self.steer(&session_id, &invocation_id, prompt)?;
                Ok(SessionDispatch {
                    response: SdkFrame::broker_response_ok(request_id, json!({ "accepted": true })),
                    events: None,
                })
            }
            "turn.abort_and_prompt" => {
                let session_id = self.resolve_session_id(object)?;
                let prompt = required_turn_prompt(object)?;
                let correlation_key = optional_string(object, "correlationKey")?;
                let invocation = self
                    .abort_and_prompt(&session_id, prompt, correlation_key.as_deref())
                    .await?;
                Ok(SessionDispatch {
                    response: SdkFrame::broker_response_ok(
                        request_id,
                        invocation_result(&invocation),
                    ),
                    events: Some(invocation.events),
                })
            }
            "turn.list" => {
                let cursor = optional_string(object, "cursor")?;
                let limit = optional_usize(object, "limit")?;
                let page = self.list(cursor.as_deref(), limit)?;
                Ok(SessionDispatch {
                    response: SdkFrame::broker_response_ok(
                        request_id,
                        serde_json::to_value(page).map_err(|error| {
                            SdkError::internal(format!("could not encode session page: {error}"))
                        })?,
                    ),
                    events: None,
                })
            }
            _ => Err(SdkError::unknown_operation(format!(
                "unknown session operation `{operation}`"
            ))),
        }
    }

    fn resolve_session_id(&self, input: &Map<String, Value>) -> SdkResult<String> {
        if let Some(value) = input.get("sessionId") {
            let session_id = value
                .as_str()
                .ok_or_else(|| SdkError::invalid_input("field `sessionId` must be a string"))?;
            validate_session_id(session_id)?;
            return Ok(session_id.to_string());
        }
        if let Some(value) = input.get("correlationKey") {
            let correlation_key = value.as_str().ok_or_else(|| {
                SdkError::invalid_input("field `correlationKey` must be a string")
            })?;
            return self
                .session_for_correlation_key(correlation_key)?
                .ok_or_else(|| {
                    SdkError::not_found("no session is associated with this correlation key")
                });
        }
        Err(SdkError::invalid_input(
            "operation requires `sessionId` or a known `correlationKey`",
        ))
    }
}

fn invocation_result(invocation: &SessionInvocation) -> Value {
    json!({
        "sessionId": invocation.session_id,
        "invocationId": invocation.invocation_id,
    })
}

fn finish_invocation(
    inner: &SessionRouterInner,
    session_id: &str,
    invocation_id: &str,
    correlation_key: Option<&str>,
    control: &TurnControlSignal,
    publisher: &SessionEventPublisher,
    result: SessionRunResult,
) {
    let _reconciliation_guard = inner
        .reconciliation_lock
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner);
    let _publication_guard = publisher.lock();
    control.close();

    let (outcome, message_count, status, error_message) = match result {
        SessionRunResult::Completed(session) => (
            InvocationOutcome::Completed {
                message_count: session.messages.len(),
            },
            session.messages.len(),
            "completed",
            None,
        ),
        SessionRunResult::Aborted(session) => (
            InvocationOutcome::Aborted {
                message_count: session.messages.len(),
            },
            session.messages.len(),
            "aborted",
            None,
        ),
        SessionRunResult::Failed { session, message } => (
            InvocationOutcome::Failed {
                message: message.clone(),
                message_count: session.messages.len(),
            },
            session.messages.len(),
            "failed",
            Some(message),
        ),
    };
    let mut payload = json!({ "status": status, "messageCount": message_count });
    if let Some(error) = error_message {
        payload["error"] = Value::String(error);
    }
    let terminal_event = publisher.build_locked(SessionEventType::TurnEnded, payload, true);
    let stored_event = match serde_json::to_value(&terminal_event) {
        Ok(event) => event,
        Err(error) => {
            let _ = inner
                .reconciliation
                .mark_uncertain(invocation_id, error.to_string());
            return;
        }
    };
    if let Err(error) = inner.reconciliation.record_pending_terminal(
        invocation_id,
        outcome.clone(),
        stored_event.clone(),
    ) {
        let _ = inner
            .reconciliation
            .mark_uncertain(invocation_id, error.to_string());
        return;
    }
    let terminal_scope_revision = match correlation_key {
        Some(key) => match inner.terminal_scopes.set(key, session_id) {
            Ok(scope) => Some(scope.revision),
            Err(error) => {
                let _ = inner
                    .reconciliation
                    .mark_uncertain(invocation_id, error.to_string());
                return;
            }
        },
        None => None,
    };
    match inner.reconciliation.record_terminal_with_scope_revision(
        invocation_id,
        outcome,
        Some(stored_event),
        terminal_scope_revision,
    ) {
        Ok(()) => {
            let _ = publisher.sender.send(terminal_event);
        }
        Err(error) => {
            let _ = inner
                .reconciliation
                .mark_uncertain(invocation_id, error.to_string());
        }
    }
}

fn recover_terminal_scopes(
    reconciliation: &InvocationReconciliationStore,
    terminal_scopes: &TerminalScopeStore,
) -> SdkResult<()> {
    let mut latest_by_key = BTreeMap::<String, (u64, String)>::new();
    for record in reconciliation.list()? {
        if record.status != InvocationStatus::Terminal {
            continue;
        }
        let Some(key) = record.correlation_key.as_ref() else {
            continue;
        };
        let Some(revision) = record.terminal_scope_revision else {
            continue;
        };
        match latest_by_key.get(key) {
            Some((current_revision, current_session)) if *current_revision == revision => {
                if current_session != &record.session_id {
                    return Err(SdkError::internal(format!(
                        "terminal scope revision {revision} conflicts for key '{key}'"
                    )));
                }
            }
            Some((current_revision, _)) if *current_revision > revision => {}
            _ => {
                latest_by_key.insert(key.clone(), (revision, record.session_id));
            }
        }
    }
    for (key, (revision, session_id)) in latest_by_key {
        validate_correlation_key(&key)?;
        terminal_scopes.restore_if_newer(&key, &session_id, revision)?;
    }
    Ok(())
}

fn recover_pending_terminal_outcomes(
    reconciliation: &InvocationReconciliationStore,
    terminal_scopes: &TerminalScopeStore,
) -> SdkResult<()> {
    let records = reconciliation.list()?;
    let mut latest_terminal_update = BTreeMap::<String, u64>::new();
    let mut original_scope_update = BTreeMap::<String, Option<u64>>::new();
    let mut pending = Vec::new();
    for record in records {
        if record.status == InvocationStatus::Terminal {
            if let Some(key) = record.correlation_key.as_ref() {
                latest_terminal_update
                    .entry(key.clone())
                    .and_modify(|updated_at| *updated_at = (*updated_at).max(record.updated_at_ms))
                    .or_insert(record.updated_at_ms);
            }
        } else if record.outcome.is_some() && record.terminal_event.is_some() {
            pending.push(record);
        }
    }
    pending.sort_by(|left, right| {
        left.updated_at_ms
            .cmp(&right.updated_at_ms)
            .then_with(|| left.invocation_id.cmp(&right.invocation_id))
    });

    for record in pending {
        let scope_revision = match record.correlation_key.as_deref() {
            Some(key) => {
                let scope_updated_at = if let Some(updated_at) = original_scope_update.get(key) {
                    *updated_at
                } else {
                    let updated_at = terminal_scopes.get(key)?.map(|scope| scope.updated_at_ms);
                    original_scope_update.insert(key.to_string(), updated_at);
                    updated_at
                };
                let newer_terminal = latest_terminal_update
                    .get(key)
                    .is_some_and(|updated_at| *updated_at >= record.updated_at_ms);
                let newer_scope =
                    scope_updated_at.is_some_and(|updated_at| updated_at >= record.updated_at_ms);
                if newer_terminal || newer_scope {
                    None
                } else {
                    Some(terminal_scopes.set(key, &record.session_id)?.revision)
                }
            }
            None => None,
        };
        reconciliation.record_terminal_with_scope_revision(
            &record.invocation_id,
            record
                .outcome
                .ok_or_else(|| SdkError::internal("pending terminal outcome is missing"))?,
            Some(
                record
                    .terminal_event
                    .ok_or_else(|| SdkError::internal("pending terminal event is missing"))?,
            ),
            scope_revision,
        )?;
    }
    Ok(())
}

fn finish_uncertain(
    inner: &SessionRouterInner,
    invocation_id: &str,
    control: &TurnControlSignal,
    publisher: &SessionEventPublisher,
    reason: &str,
) {
    let _publication_guard = publisher.lock();
    control.close();
    let _ = inner
        .reconciliation
        .mark_uncertain(invocation_id, reason.to_string());
}

fn remove_active(inner: &SessionRouterInner, session_id: &str, invocation_id: &str) {
    let mut active = inner
        .active
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner);
    if active
        .get(session_id)
        .is_some_and(|value| value.invocation_id == invocation_id)
    {
        active.remove(session_id);
    }
}

fn panic_message(panic: Box<dyn std::any::Any + Send>) -> String {
    panic
        .downcast_ref::<String>()
        .cloned()
        .or_else(|| {
            panic
                .downcast_ref::<&str>()
                .map(|value| (*value).to_string())
        })
        .unwrap_or_else(|| "session runner panicked".to_string())
}

fn validate_session_id(session_id: &str) -> SdkResult<()> {
    let is_valid = !session_id.is_empty()
        && session_id.len() <= MAX_SESSION_ID_BYTES
        && session_id
            .bytes()
            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_'));
    if is_valid {
        Ok(())
    } else {
        Err(SdkError::invalid_input("sessionId is malformed"))
    }
}

fn validate_invocation_id(invocation_id: &str) -> SdkResult<()> {
    let is_uuid = Uuid::parse_str(invocation_id).is_ok();
    if is_uuid {
        Ok(())
    } else {
        Err(SdkError::invalid_input("invocationId must be a UUID"))
    }
}

fn validate_correlation_key(correlation_key: &str) -> SdkResult<()> {
    if correlation_key.len() <= MAX_CORRELATION_KEY_BYTES {
        Ok(())
    } else {
        Err(SdkError::invalid_input("correlationKey exceeds 512 bytes"))
    }
}

fn validate_optional_correlation_key(correlation_key: Option<&str>) -> SdkResult<()> {
    correlation_key.map_or(Ok(()), validate_correlation_key)
}

fn validate_prompt(prompt: &str) -> SdkResult<()> {
    if !prompt.trim().is_empty() && prompt.len() <= 1_000_000 {
        Ok(())
    } else {
        Err(SdkError::invalid_input(
            "prompt must be non-empty and no larger than 1 MiB",
        ))
    }
}

fn required_string(object: &Map<String, Value>, key: &str) -> SdkResult<String> {
    object
        .get(key)
        .and_then(Value::as_str)
        .map(ToOwned::to_owned)
        .ok_or_else(|| SdkError::invalid_input(format!("missing string field `{key}`")))
}

fn optional_prompt(object: &Map<String, Value>, key: &str) -> SdkResult<Option<String>> {
    match object.get(key) {
        None | Some(Value::Null) => Ok(None),
        Some(value) => prompt_value(value).map(Some),
    }
}

fn required_turn_prompt(object: &Map<String, Value>) -> SdkResult<String> {
    for key in ["prompt", "request", "input"] {
        if let Some(value) = object.get(key) {
            return prompt_value(value);
        }
    }
    Err(SdkError::invalid_input(
        "operation requires a string `prompt` or `request` input",
    ))
}

fn prompt_value(value: &Value) -> SdkResult<String> {
    match value {
        Value::String(prompt) => Ok(prompt.clone()),
        Value::Object(object) => {
            if let Some(messages) = object.get("messages").and_then(Value::as_array) {
                if let Some(user_message) = messages.iter().rev().find(|message| {
                    message
                        .get("role")
                        .and_then(Value::as_str)
                        .is_some_and(|role| role == "user")
                }) {
                    if let Some(content) = user_message.get("content") {
                        return prompt_value(content);
                    }
                }
            }
            for key in ["prompt", "input", "text", "content"] {
                if let Some(value) = object.get(key) {
                    return prompt_value(value);
                }
            }
            Err(SdkError::invalid_input(
                "request object must contain prompt text or a user message",
            ))
        }
        Value::Array(blocks) => {
            let mut text = Vec::new();
            for block in blocks {
                match block {
                    Value::String(value) => text.push(value.clone()),
                    Value::Object(object) => {
                        if let Some(value) = object.get("text").and_then(Value::as_str) {
                            text.push(value.to_string());
                        } else if let Some(value) = object.get("content") {
                            text.push(prompt_value(value)?);
                        }
                    }
                    _ => {}
                }
            }
            if text.is_empty() {
                Err(SdkError::invalid_input(
                    "request content has no text blocks",
                ))
            } else {
                Ok(text.join("\n"))
            }
        }
        _ => Err(SdkError::invalid_input(
            "prompt/request content must contain text",
        )),
    }
}

fn optional_string(object: &Map<String, Value>, key: &str) -> SdkResult<Option<String>> {
    match object.get(key) {
        None | Some(Value::Null) => Ok(None),
        Some(Value::String(value)) => Ok(Some(value.clone())),
        Some(_) => Err(SdkError::invalid_input(format!(
            "field `{key}` must be a string"
        ))),
    }
}

fn optional_usize(object: &Map<String, Value>, key: &str) -> SdkResult<Option<usize>> {
    match object.get(key) {
        None | Some(Value::Null) => Ok(None),
        Some(Value::Number(value)) => value
            .as_u64()
            .and_then(|number| usize::try_from(number).ok())
            .map(Some)
            .ok_or_else(|| SdkError::invalid_input(format!("field `{key}` must be positive"))),
        Some(_) => Err(SdkError::invalid_input(format!(
            "field `{key}` must be an integer"
        ))),
    }
}

fn now_ms() -> u64 {
    SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map_or(0, |duration| {
            duration.as_millis().min(u128::from(u64::MAX)) as u64
        })
}