bamboo_engine/
app_context.rs

1//! Dependency-inversion context for the agent-session-orchestration cluster.
2//!
3//! The session/event/title/gold modules that live in this crate need a handful
4//! of shared application resources (sessions cache, storage, persistence,
5//! providers, the per-session event senders, and the account change-feed sink).
6//! Historically those were reached through the server's `AppState`, which
7//! coupled the cluster to the actix-web server crate.
8//!
9//! [`AgentSessionContext`] inverts that dependency: the cluster depends only on
10//! this trait, and the server implements it on `AppState`. This keeps the
11//! orchestration code free of any HTTP / server types.
12//!
13//! Accessor return types are deliberately the *exact* field types `AppState`
14//! already exposes, so the server-side impl is a thin delegation and no copying
15//! is introduced. Provider lookups return `Option` (the server's fallible
16//! lookups discard the error type, which is actix-coupled).
17
18use std::collections::HashMap;
19use std::sync::Arc;
20
21use async_trait::async_trait;
22use tokio::sync::{broadcast, RwLock};
23
24use bamboo_agent_core::storage::Storage;
25use bamboo_agent_core::{AgentEvent, Session};
26use bamboo_domain::ProviderModelRef;
27use bamboo_infrastructure::{Config, LLMProvider, LockedSessionStore, ProviderRegistry};
28
29use crate::events::AccountEventSink;
30use crate::runtime::execution::runner_state::AgentRunner;
31
32/// Shared application context the agent-session-orchestration cluster depends
33/// on, in place of the server's concrete `AppState`.
34///
35/// Implemented by the server on `AppState`. Every accessor mirrors an existing
36/// `AppState` field or method; the trait exists solely to invert the
37/// cluster→server dependency.
38#[async_trait]
39pub trait AgentSessionContext: Send + Sync {
40    /// In-memory session cache.
41    fn sessions(&self) -> &Arc<RwLock<HashMap<String, Session>>>;
42
43    /// Persistent session storage backend.
44    fn storage(&self) -> &Arc<dyn Storage>;
45
46    /// Per-session write-serialising persistence layer.
47    fn persistence(&self) -> &Arc<LockedSessionStore>;
48
49    /// Active agent runners, keyed by session id.
50    fn agent_runners(&self) -> &Arc<RwLock<HashMap<String, AgentRunner>>>;
51
52    /// Account-wide durable change-feed sink.
53    fn account_sink(&self) -> &Arc<AccountEventSink>;
54
55    /// Hot-reloadable application configuration.
56    fn config(&self) -> &Arc<RwLock<Config>>;
57
58    /// Multi-provider registry.
59    fn provider_registry(&self) -> &Arc<ProviderRegistry>;
60
61    /// Get (or create) the long-lived broadcast sender for a session's events.
62    async fn get_session_event_sender(&self, session_id: &str) -> broadcast::Sender<AgentEvent>;
63
64    /// Load a session, merging the in-memory and on-disk copies.
65    async fn load_session_merged(&self, session_id: &str) -> Option<Session>;
66
67    /// Persist a session and refresh the in-memory cache.
68    async fn save_and_cache_session(&self, session: &mut Session);
69
70    /// Get the always-current default provider handle.
71    async fn get_provider(&self) -> Arc<dyn LLMProvider>;
72
73    /// Route to a provider for a specific provider/model ref.
74    ///
75    /// Returns `None` on failure (the server's fallible lookup discards its
76    /// actix-coupled error type).
77    fn get_provider_for_model_ref(&self, target: &ProviderModelRef)
78        -> Option<Arc<dyn LLMProvider>>;
79
80    /// Resolve a provider for a named provider endpoint.
81    ///
82    /// Returns `None` on failure (see [`Self::get_provider_for_model_ref`]).
83    async fn get_provider_for_endpoint(&self, provider_name: &str)
84        -> Option<Arc<dyn LLMProvider>>;
85
86    /// Try to claim the title-generation slot for `session_id`.
87    /// Returns `true` on success, `false` if generation is already in flight.
88    fn title_gen_acquire(&self, session_id: &str) -> bool;
89
90    /// Release the title-generation slot for `session_id`. Idempotent.
91    fn title_gen_release(&self, session_id: &str);
92}
bamboo_engine/app_context.rs

bamboo_engine/
app_context.rs
