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_llm::{Config, LLMProvider, ProviderRegistry};
28use bamboo_storage::LockedSessionStore;
29
30use crate::events::AccountEventSink;
31use crate::runtime::execution::runner_state::AgentRunner;
32
33/// Shared application context the agent-session-orchestration cluster depends
34/// on, in place of the server's concrete `AppState`.
35///
36/// Implemented by the server on `AppState`. Every accessor mirrors an existing
37/// `AppState` field or method; the trait exists solely to invert the
38/// cluster→server dependency.
39#[async_trait]
40pub trait AgentSessionContext: Send + Sync {
41    /// In-memory session cache.
42    fn sessions(&self) -> &crate::SessionCache;
43
44    /// Persistent session storage backend.
45    fn storage(&self) -> &Arc<dyn Storage>;
46
47    /// Per-session write-serialising persistence layer.
48    fn persistence(&self) -> &Arc<LockedSessionStore>;
49
50    /// Active agent runners, keyed by session id.
51    fn agent_runners(&self) -> &Arc<RwLock<HashMap<String, AgentRunner>>>;
52
53    /// Account-wide durable change-feed sink.
54    fn account_sink(&self) -> &Arc<AccountEventSink>;
55
56    /// Hot-reloadable application configuration.
57    fn config(&self) -> &Arc<RwLock<Config>>;
58
59    /// Multi-provider registry.
60    fn provider_registry(&self) -> &Arc<ProviderRegistry>;
61
62    /// Get (or create) the long-lived broadcast sender for a session's events.
63    async fn get_session_event_sender(&self, session_id: &str) -> broadcast::Sender<AgentEvent>;
64
65    /// Load a session, merging the in-memory and on-disk copies.
66    async fn load_session_merged(&self, session_id: &str) -> Option<Session>;
67
68    /// Persist a session and refresh the in-memory cache.
69    async fn save_and_cache_session(&self, session: &mut Session);
70
71    /// Get the always-current default provider handle.
72    async fn get_provider(&self) -> Arc<dyn LLMProvider>;
73
74    /// Route to a provider for a specific provider/model ref.
75    ///
76    /// Returns `None` on failure (the server's fallible lookup discards its
77    /// actix-coupled error type).
78    fn get_provider_for_model_ref(&self, target: &ProviderModelRef)
79        -> Option<Arc<dyn LLMProvider>>;
80
81    /// Resolve a provider for a named provider endpoint.
82    ///
83    /// Returns `None` on failure (see [`Self::get_provider_for_model_ref`]).
84    async fn get_provider_for_endpoint(&self, provider_name: &str) -> 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
