bamboo_engine/runtime/
agent.rs

1//! Stable public API for the agent runtime.
2//!
3//! [`Agent`] wraps an [`AgentRuntime`] with method-based access and serves as
4//! the primary entry point for SDK consumers.
5
6use std::sync::Arc;
7
8use bamboo_agent_core::Session;
9
10use crate::runtime::{AgentRuntime, AgentRuntimeBuilder, ExecuteRequest};
11use bamboo_domain::RuntimeSessionPersistence;
12
13// ---------------------------------------------------------------------------
14// Agent — stable public object
15// ---------------------------------------------------------------------------
16
17/// Stable public entry point for agent execution.
18///
19/// Wraps an [`AgentRuntime`] and provides:
20/// - [`Agent::execute()`] — run the agent loop on a session
21/// - [`Agent::storage()`] — access the shared storage backend
22///
23/// Clone is cheap (inner is `Arc`).
24#[derive(Clone)]
25pub struct Agent {
26    runtime: Arc<AgentRuntime>,
27}
28
29impl Agent {
30    /// Wrap an existing [`AgentRuntime`] in an `Agent`.
31    pub fn from_runtime(runtime: Arc<AgentRuntime>) -> Self {
32        Agent { runtime }
33    }
34
35    /// Return a new builder.
36    pub fn builder() -> AgentBuilder {
37        AgentBuilder::new()
38    }
39
40    /// Execute the agent loop with the given request.
41    pub async fn execute(
42        &self,
43        session: &mut Session,
44        req: ExecuteRequest,
45    ) -> crate::runtime::runner::Result<()> {
46        self.runtime.execute(session, req).await
47    }
48
49    /// Access the shared storage backend.
50    pub fn storage(&self) -> &Arc<dyn bamboo_agent_core::storage::Storage> {
51        &self.runtime.storage
52    }
53
54    /// Access the runtime persistence adapter for non-authoritative saves.
55    pub fn persistence(&self) -> &Arc<dyn RuntimeSessionPersistence> {
56        &self.runtime.persistence
57    }
58
59    /// Access the runtime's default tool executor (the root/full tool surface
60    /// assembled at build time).
61    ///
62    /// Exposed so callers can compose additional one-off dispatches against the
63    /// SAME executor the loop itself uses — e.g. re-executing a single
64    /// previously-gated tool call after a permission approval — without forking
65    /// or reaching into `AgentLoopConfig` (which stays unconstructible outside
66    /// the engine). This is a read-only accessor alongside `storage()` /
67    /// `persistence()`; it does not touch the sealed loop config.
68    pub fn default_tools(&self) -> &Arc<dyn bamboo_agent_core::tools::ToolExecutor> {
69        &self.runtime.default_tools
70    }
71}
72
73// ---------------------------------------------------------------------------
74// AgentBuilder
75// ---------------------------------------------------------------------------
76
77/// Builder for [`Agent`].
78///
79/// Delegates to [`AgentRuntimeBuilder`] internally.
80pub struct AgentBuilder {
81    inner: AgentRuntimeBuilder,
82}
83
84impl AgentBuilder {
85    pub fn new() -> Self {
86        Self {
87            inner: AgentRuntimeBuilder::new(),
88        }
89    }
90
91    pub fn storage(mut self, v: Arc<dyn bamboo_agent_core::storage::Storage>) -> Self {
92        self.inner = self.inner.storage(v);
93        self
94    }
95
96    pub fn persistence(mut self, v: Arc<dyn RuntimeSessionPersistence>) -> Self {
97        self.inner = self.inner.persistence(v);
98        self
99    }
100
101    pub fn attachment_reader(
102        mut self,
103        v: Arc<dyn bamboo_agent_core::storage::AttachmentReader>,
104    ) -> Self {
105        self.inner = self.inner.attachment_reader(v);
106        self
107    }
108
109    pub fn skill_manager(mut self, v: Arc<bamboo_skills::SkillManager>) -> Self {
110        self.inner = self.inner.skill_manager(v);
111        self
112    }
113
114    pub fn project_context_resolver(
115        mut self,
116        v: Arc<crate::project_context::ProjectContextResolver>,
117    ) -> Self {
118        self.inner = self.inner.project_context_resolver(v);
119        self
120    }
121
122    pub fn metrics_collector(mut self, v: bamboo_metrics::MetricsCollector) -> Self {
123        self.inner = self.inner.metrics_collector(v);
124        self
125    }
126
127    pub fn config(mut self, v: Arc<tokio::sync::RwLock<bamboo_llm::Config>>) -> Self {
128        self.inner = self.inner.config(v);
129        self
130    }
131
132    pub fn provider(mut self, v: Arc<dyn bamboo_llm::LLMProvider>) -> Self {
133        self.inner = self.inner.provider(v);
134        self
135    }
136
137    pub fn default_tools(mut self, v: Arc<dyn bamboo_agent_core::tools::ToolExecutor>) -> Self {
138        self.inner = self.inner.default_tools(v);
139        self
140    }
141
142    /// Install an immutable lifecycle-hook registry for this agent runtime.
143    pub fn hook_runner(mut self, v: Arc<crate::runtime::HookRunner>) -> Self {
144        self.inner = self.inner.hook_runner(v);
145        self
146    }
147
148    pub fn build(self) -> Result<Agent, &'static str> {
149        let runtime = self.inner.build()?;
150        Ok(Agent {
151            runtime: Arc::new(runtime),
152        })
153    }
154}
155
156impl Default for AgentBuilder {
157    fn default() -> Self {
158        Self::new()
159    }
160}
bamboo_engine/runtime/agent.rs

bamboo_engine/runtime/
agent.rs
