Skip to main content

tea_coding/
builder.rs

1use std::str::FromStr;
2use std::sync::Arc;
3use std::time::Duration;
4
5use tea::AgentRuntimeBuilder;
6use tea_coding_tools::{
7    BashConfig, BashTool, EditTool, FetchProvider, FindTool, GrepTool, LsTool, ReadTool,
8    SearchProvider, WebFetchTool, WebSearchTool, WorkspaceFileResourceResolver, WorkspaceRoot,
9    WriteTool,
10};
11use tea_context::{SkillMetadataProvider, WorkspaceInstructionProvider};
12use tea_kernel::ModelRetryPolicy;
13use tea_mcp::McpManager;
14use tea_model::{HostedToolOptions, ModelProvider, ReasoningEffort};
15use tea_policy::{ActorId, CodingWorkspacePolicy, ExternalSourcePolicy, WorkspaceId};
16use tea_profile::ProfileRuleId;
17use tea_session::{SessionCatalog, SessionStore};
18use tea_tools::{
19    ArgumentResourceResolver, StaticResourceResolver, ToolBinding, ToolResourceAccess,
20    ToolRoutePreference,
21};
22
23use crate::config::{
24    CodingSettings, WebFetchSettings, WebSearchRoutePreference, WebSearchSettings,
25};
26use crate::mcp_policy::CodingMcpPolicy;
27use crate::profile::{coding_identity_provider, coding_profile};
28use crate::resources::ResourceCatalog;
29use crate::{CodingAgentService, CodingError, CodingErrorCode};
30
31/// Product builder assembling one mode-neutral coding service.
32#[derive(Debug)]
33pub struct CodingAgentBuilder {
34    providers: Vec<Arc<dyn ModelProvider>>,
35    workspace: WorkspaceRoot,
36    resources: ResourceCatalog,
37    store: Arc<dyn SessionStore>,
38    catalog: Arc<dyn SessionCatalog>,
39    bash: BashConfig,
40    settings: CodingSettings,
41    actor: ActorId,
42    workspace_id: WorkspaceId,
43    compaction_summarizer: Option<Arc<dyn tea_kernel::CompactionSummarizer>>,
44    mcp_manager: Option<Arc<McpManager>>,
45    search_provider: Option<Arc<dyn SearchProvider>>,
46    fetch_provider: Option<Arc<dyn FetchProvider>>,
47}
48
49impl CodingAgentBuilder {
50    /// Creates a fully explicit, test-isolated builder.
51    #[allow(clippy::too_many_arguments)]
52    #[must_use]
53    pub fn new<S>(
54        provider: Arc<dyn ModelProvider>,
55        workspace: WorkspaceRoot,
56        resources: ResourceCatalog,
57        store: Arc<S>,
58        bash: BashConfig,
59        settings: CodingSettings,
60        actor: ActorId,
61        workspace_id: WorkspaceId,
62    ) -> Self
63    where
64        S: SessionStore + SessionCatalog + 'static,
65    {
66        let session_store: Arc<dyn SessionStore> = store.clone();
67        let session_catalog: Arc<dyn SessionCatalog> = store;
68        Self {
69            providers: vec![provider],
70            workspace,
71            resources,
72            store: session_store,
73            catalog: session_catalog,
74            bash,
75            settings,
76            actor,
77            workspace_id,
78            compaction_summarizer: None,
79            mcp_manager: None,
80            search_provider: None,
81            fetch_provider: None,
82        }
83    }
84
85    /// Registers an additional model provider in the immutable runtime generation.
86    #[must_use]
87    pub fn provider(mut self, provider: Arc<dyn ModelProvider>) -> Self {
88        self.providers.push(provider);
89        self
90    }
91
92    /// Supplies the required summarizer when automatic compaction is enabled.
93    #[must_use]
94    pub fn compaction_summarizer(
95        mut self,
96        summarizer: Arc<dyn tea_kernel::CompactionSummarizer>,
97    ) -> Self {
98        self.compaction_summarizer = Some(summarizer);
99        self
100    }
101
102    /// Injects a manager initialized before immutable runtime binding.
103    ///
104    /// The resulting service owns the manager and must be shut down normally
105    /// to await its child processes. The manager's catalog is never refreshed
106    /// during this service lifetime.
107    #[must_use]
108    pub fn mcp_manager(mut self, manager: Arc<McpManager>) -> Self {
109        self.mcp_manager = Some(manager);
110        self
111    }
112
113    /// Injects a real client web-search backend.
114    ///
115    /// Injection alone does not enable the client route and never adds
116    /// `web_search` to the active-tool allowlist. Both remain controlled by
117    /// explicit product settings.
118    #[must_use]
119    pub fn search_provider(mut self, provider: Arc<dyn SearchProvider>) -> Self {
120        self.search_provider = Some(provider);
121        self
122    }
123
124    /// Injects a real client web-fetch backend.
125    ///
126    /// Injection alone never registers or activates `web_fetch`; both the
127    /// active-tool allowlist and explicit backend enablement remain required.
128    #[must_use]
129    pub fn fetch_provider(mut self, provider: Arc<dyn FetchProvider>) -> Self {
130        self.fetch_provider = Some(provider);
131        self
132    }
133
134    /// Assembles provider, profile, policy, context, registered tools, and session ports.
135    ///
136    /// # Errors
137    ///
138    /// Returns a bounded product error for any invalid contract or registration.
139    pub fn build(self) -> Result<CodingAgentService, CodingError> {
140        crate::config::validate(&self.settings)?;
141        let profile = coding_profile(&self.settings)?;
142        let retry_attempts = self.settings.max_retries.saturating_add(1);
143        let default_reasoning_effort =
144            ReasoningEffort::from_str(&self.settings.thinking).map_err(|_| invalid_settings())?;
145        let mut builder = AgentRuntimeBuilder::new()
146            .session_store(self.store)
147            .session_catalog(self.catalog)
148            .actor(self.actor)
149            .workspace(self.workspace_id.clone())
150            .default_reasoning_effort(default_reasoning_effort)
151            .retry_policy(
152                ModelRetryPolicy::new(
153                    retry_attempts,
154                    Duration::from_millis(self.settings.retry_base_delay_ms),
155                    Duration::from_millis(self.settings.retry_max_delay_ms),
156                )
157                .map_err(|_| runtime_error())?,
158            )
159            .profile(profile)
160            .context_provider(Arc::new(coding_identity_provider()?))
161            .context_provider(Arc::new(
162                WorkspaceInstructionProvider::new(self.resources.context().to_vec())
163                    .map_err(|_| runtime_error())?,
164            ))
165            .context_provider(Arc::new(
166                SkillMetadataProvider::new(self.resources.skill_metadata())
167                    .map_err(|_| runtime_error())?,
168            ));
169        for provider in self.providers {
170            builder = builder.provider(provider);
171        }
172        if self.settings.compaction_enabled {
173            let summarizer = self.compaction_summarizer.ok_or_else(runtime_error)?;
174            builder = builder
175                .compaction_policy(Arc::new(OverflowCompactionPolicy))
176                .compaction_summarizer(summarizer);
177        }
178        builder = builder
179            .policy_rule(
180                ProfileRuleId::from_str("platform.external_source").map_err(|_| runtime_error())?,
181                Arc::new(ExternalSourcePolicy),
182            )
183            .map_err(|_| runtime_error())?
184            .policy_rule(
185                ProfileRuleId::from_str("product.coding_workspace").map_err(|_| runtime_error())?,
186                Arc::new(CodingWorkspacePolicy),
187            )
188            .map_err(|_| runtime_error())?
189            .policy_rule(
190                ProfileRuleId::from_str("product.coding_mcp").map_err(|_| runtime_error())?,
191                Arc::new(CodingMcpPolicy),
192            )
193            .map_err(|_| runtime_error())?;
194        builder = register_native_tools(builder, &self.workspace, self.bash)?;
195        builder = register_web_search(builder, &self.settings.web_search, self.search_provider)?;
196        builder = register_web_fetch(
197            builder,
198            &self.settings.active_tools,
199            &self.settings.web_fetch,
200            self.fetch_provider,
201        )?;
202        builder = register_mcp_tools(builder, self.mcp_manager.as_deref())?;
203        let runtime = builder.build().map_err(CodingError::from)?;
204        Ok(CodingAgentService::new(
205            runtime,
206            self.workspace,
207            self.resources,
208            self.settings,
209            self.workspace_id,
210            self.mcp_manager,
211        ))
212    }
213}
214
215fn register_web_fetch(
216    builder: AgentRuntimeBuilder,
217    active_tools: &[String],
218    settings: &WebFetchSettings,
219    provider: Option<Arc<dyn FetchProvider>>,
220) -> Result<AgentRuntimeBuilder, CodingError> {
221    if !active_tools.iter().any(|tool| tool == "web_fetch") {
222        return Ok(builder);
223    }
224    if !settings.enabled {
225        return Err(CodingError::new(
226            CodingErrorCode::InvalidInput,
227            "active web fetch requires an enabled client backend",
228        ));
229    }
230    let provider = provider.ok_or_else(|| {
231        CodingError::new(
232            CodingErrorCode::InvalidInput,
233            "active web fetch requires an injected fetch provider",
234        )
235    })?;
236    let resolver = ArgumentResourceResolver::new("url", "url", ToolResourceAccess::Read)
237        .map_err(|_| invalid_settings())?;
238    builder
239        .tool(
240            WebFetchTool::spec().map_err(|_| runtime_error())?,
241            Arc::new(resolver),
242            Arc::new(WebFetchTool::new(provider)),
243        )
244        .map_err(|_| runtime_error())
245}
246
247fn register_web_search(
248    builder: AgentRuntimeBuilder,
249    settings: &WebSearchSettings,
250    provider: Option<Arc<dyn SearchProvider>>,
251) -> Result<AgentRuntimeBuilder, CodingError> {
252    let options = settings.runtime_options().map_err(|_| invalid_settings())?;
253    let hosted = HostedToolOptions::WebSearch(options.clone());
254    let spec = WebSearchTool::spec().map_err(|_| runtime_error())?;
255    if settings.client.enabled {
256        if let Some(provider) = provider {
257            let tool = WebSearchTool::new(provider, options);
258            let resolver = Arc::new(
259                StaticResourceResolver::new([tool.resource().map_err(|_| invalid_settings())?])
260                    .map_err(|_| invalid_settings())?,
261            );
262            let preference = match settings.route_preference {
263                WebSearchRoutePreference::PreferHosted => ToolRoutePreference::PreferHosted,
264                WebSearchRoutePreference::ForceClient => ToolRoutePreference::ForceClient,
265            };
266            return builder
267                .tool_binding(
268                    spec,
269                    ToolBinding::hybrid(hosted, preference, resolver, Arc::new(tool)),
270                )
271                .map_err(|_| runtime_error());
272        }
273        if settings.route_preference == WebSearchRoutePreference::ForceClient {
274            return Err(CodingError::new(
275                CodingErrorCode::InvalidInput,
276                "client web search requires an injected search provider",
277            ));
278        }
279    }
280    builder
281        .tool_binding(spec, ToolBinding::hosted(hosted))
282        .map_err(|_| runtime_error())
283}
284
285fn register_native_tools(
286    mut builder: AgentRuntimeBuilder,
287    workspace: &WorkspaceRoot,
288    bash: BashConfig,
289) -> Result<AgentRuntimeBuilder, CodingError> {
290    builder = builder
291        .tool(
292            ReadTool::spec().map_err(|_| runtime_error())?,
293            Arc::new(WorkspaceFileResourceResolver::new(ToolResourceAccess::Read)),
294            Arc::new(ReadTool::new(workspace.clone())),
295        )
296        .map_err(|_| runtime_error())?;
297    builder = builder
298        .tool(
299            GrepTool::spec().map_err(|_| runtime_error())?,
300            Arc::new(WorkspaceFileResourceResolver::new(ToolResourceAccess::Read)),
301            Arc::new(GrepTool::new(workspace.clone())),
302        )
303        .map_err(|_| runtime_error())?;
304    builder = builder
305        .tool(
306            FindTool::spec().map_err(|_| runtime_error())?,
307            Arc::new(WorkspaceFileResourceResolver::new(ToolResourceAccess::Read)),
308            Arc::new(FindTool::new(workspace.clone())),
309        )
310        .map_err(|_| runtime_error())?;
311    builder = builder
312        .tool(
313            LsTool::spec().map_err(|_| runtime_error())?,
314            Arc::new(WorkspaceFileResourceResolver::new(ToolResourceAccess::Read)),
315            Arc::new(LsTool::new(workspace.clone())),
316        )
317        .map_err(|_| runtime_error())?;
318    builder = builder
319        .tool(
320            WriteTool::spec().map_err(|_| runtime_error())?,
321            Arc::new(WorkspaceFileResourceResolver::new(
322                ToolResourceAccess::Write,
323            )),
324            Arc::new(WriteTool::new(workspace.clone())),
325        )
326        .map_err(|_| runtime_error())?;
327    builder = builder
328        .tool(
329            EditTool::spec().map_err(|_| runtime_error())?,
330            Arc::new(WorkspaceFileResourceResolver::read_write()),
331            Arc::new(EditTool::new(workspace.clone())),
332        )
333        .map_err(|_| runtime_error())?;
334    builder
335        .tool(
336            BashTool::spec().map_err(|_| runtime_error())?,
337            Arc::new(
338                StaticResourceResolver::new([
339                    BashTool::workspace_resource().map_err(|_| runtime_error())?
340                ])
341                .map_err(|_| runtime_error())?,
342            ),
343            Arc::new(BashTool::new(workspace.clone(), bash)),
344        )
345        .map_err(|_| runtime_error())
346}
347
348fn register_mcp_tools(
349    mut builder: AgentRuntimeBuilder,
350    manager: Option<&McpManager>,
351) -> Result<AgentRuntimeBuilder, CodingError> {
352    let Some(manager) = manager else {
353        return Ok(builder);
354    };
355    for binding in manager.catalog().bindings() {
356        let executor = manager
357            .tool_executor(binding.spec().name())
358            .map_err(|_| runtime_error())?;
359        builder = builder
360            .register_tool(
361                binding.spec().clone(),
362                Arc::new(binding.clone()),
363                Arc::new(executor),
364            )
365            .map_err(|_| runtime_error())?;
366    }
367    Ok(builder)
368}
369
370#[derive(Debug)]
371struct OverflowCompactionPolicy;
372
373impl tea_kernel::CompactionPolicy for OverflowCompactionPolicy {
374    fn should_compact(&self, estimated_input_tokens: usize, context_window: u64) -> bool {
375        u64::try_from(estimated_input_tokens).is_ok_and(|tokens| tokens >= context_window)
376    }
377}
378
379fn runtime_error() -> CodingError {
380    CodingError::new(CodingErrorCode::Runtime, "coding runtime assembly failed")
381}
382
383fn invalid_settings() -> CodingError {
384    CodingError::new(CodingErrorCode::InvalidInput, "coding settings are invalid")
385}