Struct AppState 

pub struct AppState {

    pub app_data_dir: PathBuf,
    pub config: Arc<RwLock<Config>>,
    pub config_io_lock: Arc<Mutex<()>>,
    pub provider: Arc<RwLock<Arc<dyn LLMProvider>>>,
    pub sessions: SessionCache,
    pub storage: Arc<dyn Storage>,
    pub session_store: Arc<SessionStoreV2>,
    pub persistence: Arc<LockedSessionStore>,
    pub session_repo: SessionRepository,
    pub spawn_scheduler: Arc<SpawnScheduler>,
    pub child_completion_coordinator: Arc<ChildCompletionCoordinator>,
    pub guardian_spawner: Arc<dyn GuardianSpawner>,
    pub bash_resume_hook: Arc<dyn BashResumeHook>,
    pub schedule_store: Arc<ScheduleStore>,
    pub schedule_manager: Arc<ScheduleManager>,
    pub tool_factory: ToolSurfaceFactory,
    pub permission_checker: Arc<dyn PermissionChecker>,
    pub notification_service: Arc<NotificationService>,
    pub cancel_tokens: Arc<RwLock<HashMap<String, CancellationToken>>>,
    pub mcp_proxy_shutdown: CancellationToken,
    pub skill_manager: Arc<SkillManager>,
    pub mcp_manager: Arc<McpServerManager>,
    pub metrics_service: Arc<MetricsService>,
    pub agent_runners: Arc<RwLock<HashMap<String, AgentRunner>>>,
    pub session_event_senders: Arc<RwLock<HashMap<String, Sender<AgentEvent>>>>,
    pub account_sink: Arc<AccountEventSink>,
    pub process_registry: Arc<ProcessRegistry>,
    pub metrics_bus: Option<MetricsBus>,
    pub agent: Arc<Agent>,
    pub provider_registry: Arc<ProviderRegistry>,
    pub provider_router: Arc<ProviderModelRouter>,
    pub model_catalog: Arc<ModelCatalogService>,
    pub title_gen_in_flight: Arc<DashSet<String>>,
    pub pairing_codes: Arc<DashMap<String, PairingCodeEntry>>,
    pub agent_registry: Arc<AgentRegistry>,
    pub pairing_code_guard: Arc<PairingCodeGuard>,
    pub root_password_guard: Arc<RootPasswordGuard>,
    /* private fields */
}

Unified application state consolidating web_service and agent/server state

This struct holds all the state needed to run the Bamboo server, including configuration, LLM providers, sessions, storage, tools, skills, and metrics.

Design Goals

• Direct access: Components are directly accessible without HTTP proxies
• Hot reload: Configuration and providers can be reloaded at runtime
• Thread safety: Uses Arc for concurrent access
• Persistence: Integrates with JsonlStorage for session persistence

Component Overview

Component	Purpose	Thread-Safe
config	Application configuration	Yes (RwLock)
provider	Hot-reloadable LLM provider	Yes (RwLock)
sessions	Active conversation sessions	Yes (RwLock)
storage	Persistent session storage	Yes (Arc)
tools	Tool execution (builtin + MCP)	Yes (Arc)
skill_manager	Skill registry and execution	Yes (Arc)
mcp_manager	MCP server lifecycle	Yes (Arc)
metrics_service	Usage metrics collection	Yes (Arc)
agent_runners	Active agent executions	Yes (RwLock)

Fields

app_data_dir: PathBuf

Application data directory (configured via BAMBOO_DATA_DIR; default ${HOME}/.bamboo)

config: Arc<RwLock<Config>>

Hot-reloadable application configuration

Can be reloaded from disk at runtime using reload_config().

config_io_lock: Arc<Mutex<()>>

Serializes a config WRITE’s whole [in-memory mutation + disk persist] with a reload_config’s [disk read + in-memory swap], so a reload can never observe an in-flight-but-not-yet-persisted update and clobber it with the stale disk copy (the residual of #41). It is NOT the config RwLock — using a separate mutex keeps config READERS (the hot agent-loop path) unblocked during a write’s disk I/O. #126.

provider: Arc<RwLock<Arc<dyn LLMProvider>>>

Hot-reloadable LLM provider with direct access

This eliminates the proxy pattern where we created an AgentAppState that called back to web_service via HTTP. Now we have direct provider access.

sessions: SessionCache

Active conversation sessions (in-memory cache)

Maps session IDs to Session objects. Persisted to storage via the storage field.

storage: Arc<dyn Storage>

Persistent storage backend for sessions (V2).

Implemented as folder-per-session with a global sessions.json index.

session_store: Arc<SessionStoreV2>

Concrete session store implementation (for index/list/cleanup APIs).

persistence: Arc<LockedSessionStore>

Per-session write serialisation + metadata-merge persistence layer.

Wraps the same Storage as self.storage, adding per-session Mutex guards and authoritative-metadata-group merge semantics. Use self.persistence.merge_save_runtime(...) for any write that may race with a UI metadata update.

session_repo: SessionRepository

Framework-owned session coordinator (cache + storage + persistence). The canonical load/save coordination lives here in bamboo-engine, not on AppState; the inherent AppState::load_session/save_and_cache_session methods now delegate to it. Holds clones of the same Arcs as the sessions/storage/persistence fields above.

spawn_scheduler: Arc<SpawnScheduler>

Background scheduler for async sub-session spawning.

child_completion_coordinator: Arc<ChildCompletionCoordinator>

Coordinates child completion notifications into parent resume.

guardian_spawner: Arc<dyn GuardianSpawner>

Spawner for the guardian adversarial-review child, injected into each run so the terminal gate can create a read-only reviewer (the engine runner cannot construct a child directly — see bamboo_engine::GuardianSpawner). Backed by a dedicated crate::tools::ChildSessionAdapter.

bash_resume_hook: Arc<dyn BashResumeHook>

Bash self-resume hook (issue #84 Phase 2b). Backed by the same [ChildCompletionCoordinator] that handles child-completion resumes — it polls the live shell registry and resumes a session once all its background bash shells finish.

schedule_store: Arc<ScheduleStore>

Schedule store (timed tasks).

schedule_manager: Arc<ScheduleManager>

Background schedule manager that triggers scheduled runs.

tool_factory: ToolSurfaceFactory

Tool surface factory providing pre-built tool executors for each session type.

Use state.tools_for(ToolSurface::Root) for root sessions, state.tools_for(ToolSurface::Child) for child sessions, etc.

permission_checker: Arc<dyn PermissionChecker>

Shared tool-execution permission checker — the same Arc the tool executors use. Retained so request handlers can record session grants when the user approves a permission prompt (see the respond handler).

notification_service: Arc<NotificationService>

Backend notification policy service (preferences + dedup + per-session relays). Classifies agent events into AgentEvent::Notification for clients to render; preferences are persisted server-side.

cancel_tokens: Arc<RwLock<HashMap<String, CancellationToken>>>

Cancellation tokens for in-flight requests

Maps request/session IDs to their cancellation tokens, allowing graceful shutdown of long-running operations.

mcp_proxy_shutdown: CancellationToken

Cancels the supervised MCP proxy service (issue #47) on shutdown so the reconnect/backoff supervisor stops cleanly instead of looping forever after an intended stop. Unused when no broker is configured.

skill_manager: Arc<SkillManager>

Skill manager for prompt-based skill execution

Manages the skill registry and handles skill lookup, validation, and execution.

mcp_manager: Arc<McpServerManager>

MCP server manager for external tool servers

Handles lifecycle of Model Context Protocol servers, including initialization, tool discovery, and shutdown.

metrics_service: Arc<MetricsService>

Metrics collection and persistence service

Tracks token usage, costs, and performance metrics across all sessions.

agent_runners: Arc<RwLock<HashMap<String, AgentRunner>>>

Active agent runners indexed by session ID

Each runner manages event broadcasting and cancellation for an active agent execution.

session_event_senders: Arc<RwLock<HashMap<String, Sender<AgentEvent>>>>

Session-scoped event streams (long-lived).

Unlike agent_runners, these senders exist even when no agent execution is running. They are used for:

• UI subscriptions to /api/v1/events/{session_id} (background tasks, etc.)
• sub-session forwarding (child -> parent)

account_sink: Arc<AccountEventSink>

Account-scoped durable change feed (powers GET /api/v1/stream).

Unlike session_event_senders, this is a single account-wide sink: all durable change events (message appended, session metadata, task updates, terminal status) across every session are sequenced, journaled to disk, and broadcast here for resumable multi-client sync.

process_registry: Arc<ProcessRegistry>

Registry for tracking external processes.

metrics_bus: Option<MetricsBus>

Optional metrics bus for event streaming

When enabled, allows subscribing to metrics events in real-time.

agent: Arc<Agent>

Unified agent execution runtime holding shared resources.

provider_registry: Arc<ProviderRegistry>

Multi-provider registry (used when features.provider_model_ref is enabled).

provider_router: Arc<ProviderModelRouter>

Provider/model router (used when features.provider_model_ref is enabled).

model_catalog: Arc<ModelCatalogService>

Unified model catalog service (used when features.provider_model_ref is enabled).

title_gen_in_flight: Arc<DashSet<String>>

Tracks session ids whose auto-title generation is currently in flight.

Used by crate::title_gen to dedupe concurrent invocations (e.g. execute handler firing while a regenerate-title request is running).

pairing_codes: Arc<DashMap<String, PairingCodeEntry>>

v2-P2 (#181, slice 2): in-memory one-time pairing codes. A 6-digit numeric code (keyed by the code string) maps to an entry holding its expiry. Codes are PROCESS-EPHEMERAL — never persisted to config.json; a restart drops all outstanding codes by design. Keyed by Instant-based expiry; expired entries are purged opportunistically on insert/lookup.

agent_registry: Arc<AgentRegistry>

remote-actor P2a (#181): the in-memory /v1/agents control-plane registry. Cross-host agent discovery — the network counterpart of the local-file bamboo_subagent::FileFabric. Workers on other machines register/heartbeat here; parents resolve/list/withdraw. PROCESS-EPHEMERAL — never persisted; a restart drops all registrations (workers re-register on their next heartbeat). Lease expiry is enforced lazily on read (see crate::handlers::agent::agents::AgentRegistry).

pairing_code_guard: Arc<PairingCodeGuard>

v2-P2 (#181, slice 2): per-process brute-force guard for the public code-redemption path (POST /v2/pair { code }). A 6-digit code is only ~1M space, so a public redeem endpoint is brute-forceable without a guard. Tracks recent FAILED code-redemption attempts and a cooldown deadline.

root_password_guard: Arc<RootPasswordGuard>

#190: per-client-IP brute-force guard for the public root-password endpoints (POST /v1/bamboo/access/verify and the root-password path of POST /v2/pair). Tracks recent FAILED root-password attempts per IP and a per-key cooldown; loopback/desktop requests are exempted by the handlers so the desktop can never lock itself out. PROCESS-EPHEMERAL — never persisted; a restart clears all counters.

Implementations

impl AppState

pub async fn new(bamboo_home_dir: PathBuf) -> Result<Self, AppError>

Create unified app state with direct provider access

This eliminates the proxy pattern where we created an AgentAppState that called back to web_service via HTTP. Now we have direct provider access.

Arguments

• bamboo_home_dir - Bamboo home directory containing all application data. This is the root directory (e.g., ${HOME}/.bamboo) that contains:
  • config.json: Configuration file
  • sessions/: Conversation history
  • skills/: Skill definitions
  • workflows/: Workflow definitions
  • cache/: Cached data
  • runtime/: Runtime files

Returns

A fully initialized AppState with all components ready for use.

Example

use bamboo_server::app_state::AppState;
use std::path::PathBuf;

#[tokio::main]
async fn main() {
    let state = AppState::new(PathBuf::from("/path/to/bamboo-data-dir"))
        .await
        .expect("failed to initialize app state");
    let provider = state.get_provider().await;
    let _models = provider.list_models().await.ok();
}

pub async fn new_with_provider( bamboo_home_dir: PathBuf, config: Config, provider: Arc<dyn LLMProvider>, ) -> Result<Self, AppError>

Create unified app state with a specific provider

Allows injecting a custom LLM provider instead of creating one from configuration. Useful for testing and custom deployments.

Arguments

• bamboo_home_dir - Bamboo home directory containing all application data
• config - Application configuration
• provider - Pre-configured LLM provider implementation

Returns

A fully initialized AppState with the provided provider.

impl AppState

pub async fn reload_provider(&self) -> Result<(), LLMError>

Reload the provider based on current configuration

Re-reads the configuration and creates a new LLM provider instance, allowing runtime switching of providers or models.

Returns

Ok(()) if the provider was successfully reloaded.

Errors

Returns an error if:

• Configuration cannot be read
• Provider initialization fails (e.g., invalid API key)

Example

use bamboo_server::app_state::AppState;
use std::path::PathBuf;

#[tokio::main]
async fn main() {
    let state = AppState::new(PathBuf::from("/path/to/.bamboo"))
        .await
        .expect("failed to initialize app state");

    // User updated config file...
    state.reload_provider().await.expect("Provider reload failed");
}

pub async fn reload_config(&self) -> Config

Reload the configuration from file

Reads the configuration file again and updates the in-memory config. Note: This does NOT automatically reload the provider; call reload_provider() afterwards if needed.

Returns

The newly loaded configuration.

Example

use bamboo_server::app_state::AppState;
use std::path::PathBuf;

#[tokio::main]
async fn main() {
    let state = AppState::new(PathBuf::from("/path/to/.bamboo"))
        .await
        .expect("failed to initialize app state");

    // Reload config from disk
    let new_config = state.reload_config().await;

    // Optionally reload provider with new config
    state.reload_provider().await.ok();
}

pub async fn update_config<F>( &self, update: F, effects: ConfigUpdateEffects, ) -> Result<Config, AppError>

where F: FnOnce(&mut Config) -> Result<(), AppError>,

Unified config update entrypoint.

Invariants:

• Update in-memory first
• Persist to disk
• Apply runtime side-effects last (provider reload, MCP reconcile)

pub async fn replace_config( &self, new_config: Config, effects: ConfigUpdateEffects, ) -> Result<Config, AppError>

Replace the full config (used for JSON merge endpoints).

impl AppState

pub async fn save_session(&self, session: &mut Session)

Save a complete session to persistent storage.

Uses bamboo_storage::LockedSessionStore::merge_save_runtime so any concurrent UI edits to the authoritative metadata group (title, title_version, pinned, metadata_version) are preserved when our runtime-side metadata_version does not strictly exceed disk’s.

Arguments

• session - Session object to save (mutated in-place to reflect the merged authoritative metadata values).

impl AppState

pub async fn get_provider(&self) -> Arc<dyn LLMProvider>

Get a clone of the current provider

Returns a thread-safe reference to the current LLM provider. This is the preferred way to access the provider for making requests.

Returns

An Arc reference to the current provider implementation.

Example

use bamboo_server::app_state::AppState;
use std::path::PathBuf;

#[tokio::main]
async fn main() {
    let state = AppState::new(PathBuf::from("/path/to/.bamboo"))
        .await
        .expect("failed to initialize app state");
    let provider = state.get_provider().await;

    // Use provider to make LLM requests...
}

pub fn get_provider_for_model_ref( &self, target: &ProviderModelRef, ) -> Result<Arc<dyn LLMProvider>, AppError>

Get a provider for a specific [ProviderModelRef].

Used when features.provider_model_ref is enabled to route requests to the correct provider based on the model reference.

pub async fn get_provider_for_endpoint( &self, provider_name: &str, ) -> Result<Arc<dyn LLMProvider>, AppError>

Get the appropriate provider for a named provider endpoint (e.g., “openai”, “anthropic”).

Uses the registry when the provider_model_ref feature flag is enabled, otherwise falls back to the default provider.

pub async fn shutdown(&self)

Shutdown all MCP servers gracefully

Sends shutdown signals to all running MCP server processes and waits for them to terminate cleanly.

This should be called during application shutdown to ensure MCP servers are not left running as orphaned processes. Invoked by [crate::server::web_service::WebService::stop]. #119.

pub fn tools_for(&self, surface: ToolSurface) -> Arc<dyn ToolExecutor>

Get the tool executor for a specific surface variant.

Use ToolSurface::Root for primary sessions, ToolSurface::Child for child sessions, etc.

pub fn get_all_tool_schemas(&self) -> Vec<ToolSchema>

Get all tool schemas from the composite tool executor

Returns schemas for both built-in tools and MCP-provided tools. These schemas are used to inform the LLM about available tools.

Returns

Vector of tool schemas in Anthropic’s tool definition format.

impl AppState

pub async fn get_session_event_sender( &self, session_id: &str, ) -> Sender<AgentEvent>

Get (or create) a long-lived session event sender for a session id.

This stream is intended for UI consumption and background activity; it should remain available even when no agent execution is running.

pub fn ensure_notification_relay( &self, session_id: &str, sender: Sender<AgentEvent>, )

Ensure a notification relay task is running for session_id.

The relay subscribes to the session’s event broadcast, runs the backend notification policy on each event, and re-broadcasts any resulting AgentEvent::Notification onto the same channel so connected SSE clients receive it. Idempotent: at most one relay per session (tracked by the notification service). The relay does not hold a Sender clone, so the channel still closes naturally when the session is torn down.

impl AppState

pub async fn load_session(&self, session_id: &str) -> Option<Session>

Load a session from memory cache, falling back to persistent storage.

pub async fn load_or_create_session( &self, session_id: &str, model: &str, ) -> Session

Load a session, creating a new one if it doesn’t exist.

pub async fn load_session_merged(&self, session_id: &str) -> Option<Session>

Load a session, merging memory and storage using a preference heuristic.

pub async fn save_and_cache_session(&self, session: &mut Session)

Persist session to storage and update the in-memory cache.

impl AppState

pub fn title_gen_acquire(&self, session_id: &str) -> bool

Try to claim the title-generation slot for session_id. Returns true on success, false if generation is already in flight.

pub fn title_gen_release(&self, session_id: &str)

Release the title-generation slot for session_id. Idempotent.

Trait Implementations

impl AgentSessionContext for AppState

fn sessions(&self) -> &SessionCache

In-memory session cache.

fn storage(&self) -> &Arc<dyn Storage>

Persistent session storage backend.

fn persistence(&self) -> &Arc<LockedSessionStore>

Per-session write-serialising persistence layer.

fn agent_runners(&self) -> &Arc<RwLock<HashMap<String, AgentRunner>>>

Active agent runners, keyed by session id.

fn account_sink(&self) -> &Arc<AccountEventSink>

Account-wide durable change-feed sink.

fn config(&self) -> &Arc<RwLock<Config>>

Hot-reloadable application configuration.

fn provider_registry(&self) -> &Arc<ProviderRegistry>

Multi-provider registry.

fn get_session_event_sender<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Sender<AgentEvent>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Get (or create) the long-lived broadcast sender for a session’s events.

fn load_session_merged<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Option<Session>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Load a session, merging the in-memory and on-disk copies.

fn save_and_cache_session<'life0, 'life1, 'async_trait>( &'life0 self, session: &'life1 mut Session, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Persist a session and refresh the in-memory cache.

fn get_provider<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Arc<dyn LLMProvider>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Get the always-current default provider handle.

fn get_provider_for_model_ref( &self, target: &ProviderModelRef, ) -> Option<Arc<dyn LLMProvider>>

Route to a provider for a specific provider/model ref.

fn get_provider_for_endpoint<'life0, 'life1, 'async_trait>( &'life0 self, provider_name: &'life1 str, ) -> Pin<Box<dyn Future<Output = Option<Arc<dyn LLMProvider>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Resolve a provider for a named provider endpoint.

fn title_gen_acquire(&self, session_id: &str) -> bool

Try to claim the title-generation slot for session_id. Returns true on success, false if generation is already in flight.

fn title_gen_release(&self, session_id: &str)

Release the title-generation slot for session_id. Idempotent.

impl SessionAccess for AppState

fn load_session<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<Session>, SessionLoadError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Load a session by ID (from cache or storage).

fn load_or_create<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, id: &'life1 str, model: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<Session, SessionLoadError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Load an existing session or create a new one with the given model.

fn load_merged<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<Session>, SessionLoadError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Load a session, merging memory and storage using a preference heuristic.

fn save_session<'life0, 'life1, 'async_trait>( &'life0 self, session: &'life1 mut Session, ) -> Pin<Box<dyn Future<Output = Result<(), SessionSaveError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Save a session to persistent storage only.

fn save_and_cache<'life0, 'life1, 'async_trait>( &'life0 self, session: &'life1 mut Session, ) -> Pin<Box<dyn Future<Output = Result<(), SessionSaveError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Save a session to persistent storage and update the in-memory cache.