aether_project/
agent_catalog.rs

1use crate::aether_settings::{project_settings_exist, user_settings_exist};
2use crate::error::SettingsError;
3use crate::{AetherSettings, AgentConfig, McpSourceSpec};
4use aether_core::agent_spec::{AgentSpec, AgentSpecExposure};
5use aether_core::core::{AgentRegistry, Prompt};
6use aether_core::mcp::McpConfig;
7use llm::catalog::{LlmModel, ModelSpec, ModelSpecError};
8use llm::{ProviderConnectionOverrides, ReasoningEffort};
9use std::collections::HashSet;
10use std::path::{Path, PathBuf};
11
12/// A resolved catalog of agents from a project.
13#[derive(Debug, Clone)]
14pub struct AgentCatalog {
15    project_root: PathBuf,
16    registry: AgentRegistry,
17    selected_agent: Option<String>,
18    provider_connections: ProviderConnectionOverrides,
19}
20
21impl AgentCatalog {
22    pub fn load_default(project_root: &Path) -> Result<Option<Self>, SettingsError> {
23        let has_default_settings = user_settings_exist() || project_settings_exist(project_root);
24        let settings = AetherSettings::load_default(project_root)?;
25        if settings.agents.is_empty() && !has_default_settings {
26            return Ok(None);
27        }
28
29        let catalog = Self::from_settings(project_root, settings)?;
30        if catalog.user_invocable().next().is_none() {
31            return Err(SettingsError::NoUserInvocableAgents);
32        }
33
34        Ok(Some(catalog))
35    }
36
37    pub fn from_settings_or_empty(project_root: &Path, settings: AetherSettings) -> Result<Self, SettingsError> {
38        if settings.agents.is_empty() {
39            return Ok(Self::with_defaults(project_root.to_path_buf(), Vec::new(), None, settings.providers));
40        }
41        Self::from_settings(project_root, settings)
42    }
43
44    pub fn from_settings(project_root: &Path, settings: AetherSettings) -> Result<Self, SettingsError> {
45        validate_selected_agent(&settings)?;
46        let selected_agent =
47            settings.agent.as_deref().map(str::trim).filter(|name| !name.is_empty()).map(str::to_string);
48        let provider_connections = settings.providers.clone();
49        let defaults = AgentDefaults { prompts: settings.prompts, mcps: settings.mcps, providers: settings.providers };
50        let mut seen_names = HashSet::new();
51        let mut specs = Vec::with_capacity(settings.agents.len());
52        for (index, entry) in settings.agents.into_iter().enumerate() {
53            specs.push(resolve_agent_entry(project_root, entry, &defaults, index, &mut seen_names)?);
54        }
55
56        Ok(Self::with_defaults(project_root.to_path_buf(), specs, selected_agent, provider_connections))
57    }
58
59    pub fn new(project_root: PathBuf, specs: Vec<AgentSpec>, selected_agent: Option<String>) -> Self {
60        Self::with_defaults(project_root, specs, selected_agent, ProviderConnectionOverrides::default())
61    }
62
63    #[must_use]
64    pub fn with_provider_connections(mut self, overrides: ProviderConnectionOverrides) -> Self {
65        if overrides.is_empty() {
66            return self;
67        }
68
69        let specs = self
70            .registry
71            .all()
72            .iter()
73            .cloned()
74            .map(|mut spec| {
75                spec.provider_connections.merge(overrides.clone());
76                spec
77            })
78            .collect();
79
80        self.registry = AgentRegistry::new(specs);
81        self.provider_connections.merge(overrides);
82        self
83    }
84
85    /// Create an empty catalog for a project with no settings.
86    pub fn empty(project_root: PathBuf) -> Self {
87        Self::new(project_root, Vec::new(), None)
88    }
89
90    /// The project root directory.
91    pub fn project_root(&self) -> &Path {
92        &self.project_root
93    }
94
95    /// Get all agent specs in the catalog.
96    pub fn all(&self) -> &[AgentSpec] {
97        self.registry.all()
98    }
99
100    pub fn selected_agent(&self) -> Option<&str> {
101        self.selected_agent.as_deref()
102    }
103
104    pub fn default_agent(&self) -> Option<&AgentSpec> {
105        self.selected_agent.as_deref().and_then(|name| self.registry.get(name)).or_else(|| self.user_invocable().next())
106    }
107
108    /// Get a specific agent by name.
109    pub fn get(&self, name: &str) -> Result<&AgentSpec, SettingsError> {
110        self.registry.get(name).ok_or_else(|| SettingsError::AgentNotFound { name: name.to_string() })
111    }
112
113    /// Iterate over user-invocable agents.
114    pub fn user_invocable(&self) -> impl Iterator<Item = &AgentSpec> {
115        self.registry.all().iter().filter(|s| s.exposure.user_invocable)
116    }
117
118    /// Iterate over agent-invocable agents.
119    pub fn agent_invocable(&self) -> impl Iterator<Item = &AgentSpec> {
120        self.registry.agent_invocable()
121    }
122
123    pub fn registry(&self) -> &AgentRegistry {
124        &self.registry
125    }
126
127    pub fn default_spec(&self, model: &LlmModel, reasoning_effort: Option<ReasoningEffort>) -> AgentSpec {
128        let mut spec = AgentSpec::bare(model, reasoning_effort, Vec::new());
129        spec.provider_connections.merge(self.provider_connections.clone());
130        spec
131    }
132
133    /// Resolve and return a named agent spec ready for runtime use.
134    pub fn resolve(&self, name: &str) -> Result<AgentSpec, SettingsError> {
135        self.get(name).cloned()
136    }
137}
138
139impl AgentCatalog {
140    fn with_defaults(
141        project_root: PathBuf,
142        specs: Vec<AgentSpec>,
143        selected_agent: Option<String>,
144        provider_connections: ProviderConnectionOverrides,
145    ) -> Self {
146        Self { project_root, registry: AgentRegistry::new(specs), selected_agent, provider_connections }
147    }
148}
149
150struct AgentDefaults {
151    prompts: Vec<crate::PromptSource>,
152    mcps: Vec<McpSourceSpec>,
153    providers: ProviderConnectionOverrides,
154}
155
156fn validate_selected_agent(settings: &AetherSettings) -> Result<(), SettingsError> {
157    if settings.agents.is_empty() {
158        return Err(SettingsError::EmptyAgents);
159    }
160
161    if let Some(agent) = settings.agent.as_deref() {
162        let selector = agent.trim();
163        let Some(entry) = settings.agents.iter().find(|entry| entry.name.trim() == selector) else {
164            return Err(SettingsError::InvalidAgentSelector { name: selector.to_string() });
165        };
166
167        if !entry.user_invocable {
168            return Err(SettingsError::NonUserInvocableAgentSelector { name: selector.to_string() });
169        }
170    }
171
172    Ok(())
173}
174
175fn resolve_agent_entry(
176    project_root: &Path,
177    entry: AgentConfig,
178    defaults: &AgentDefaults,
179    index: usize,
180    seen_names: &mut HashSet<String>,
181) -> Result<AgentSpec, SettingsError> {
182    let name = entry.name.trim().to_string();
183    if name.is_empty() {
184        return Err(SettingsError::EmptyAgentName { index });
185    }
186    if name == "__default__" {
187        return Err(SettingsError::ReservedAgentName { name });
188    }
189    if !seen_names.insert(name.clone()) {
190        return Err(SettingsError::DuplicateAgentName { name });
191    }
192
193    let description = entry.description.trim().to_string();
194    if description.is_empty() {
195        return Err(SettingsError::MissingField { agent: name.clone(), field: "description".to_string() });
196    }
197
198    let model = parse_model(&name, &entry.model)?;
199    model
200        .validate_reasoning_effort(entry.reasoning_effort)
201        .map_err(|source| SettingsError::InvalidReasoningEffort { agent: name.clone(), source })?;
202    if entry.context_window == Some(0) {
203        return Err(SettingsError::InvalidContextWindow { agent: name.clone(), context_window: 0 });
204    }
205    if !entry.user_invocable && !entry.agent_invocable {
206        return Err(SettingsError::NoInvocationSurface { agent: name.clone() });
207    }
208    let prompt_sources = if entry.prompts.is_empty() { &defaults.prompts } else { &entry.prompts };
209    let prompts = Prompt::from_sources(project_root, prompt_sources)
210        .map_err(|source| SettingsError::AgentPromptSource { agent: name.clone(), source })?;
211    if prompts.is_empty() {
212        return Err(if prompt_sources.is_empty() {
213            SettingsError::NoPromptsDeclared { agent: name.clone() }
214        } else {
215            SettingsError::AllOptionalPromptsMissing { agent: name.clone() }
216        });
217    }
218    let mcp_sources = if entry.mcps.is_empty() { &defaults.mcps } else { &entry.mcps };
219    let mcp = load_mcp_config(project_root, mcp_sources)?;
220    let mut provider_connections = defaults.providers.clone();
221    provider_connections.merge(entry.providers);
222
223    Ok(AgentSpec {
224        name,
225        description,
226        model: model.to_string(),
227        reasoning_effort: entry.reasoning_effort,
228        model_settings: entry.model_settings,
229        context_window: entry.context_window,
230        prompts,
231        provider_connections,
232        mcp,
233        exposure: AgentSpecExposure { user_invocable: entry.user_invocable, agent_invocable: entry.agent_invocable },
234        tools: entry.tools,
235    })
236}
237
238fn load_mcp_config(workspace_root: &Path, entries: &[McpSourceSpec]) -> Result<McpConfig, SettingsError> {
239    entries.iter().filter_map(|entry| entry.load(workspace_root).transpose()).collect()
240}
241
242fn parse_model(agent: &str, model: &str) -> Result<ModelSpec, SettingsError> {
243    model.parse().map_err(|error: ModelSpecError| SettingsError::InvalidModel {
244        agent: agent.to_string(),
245        model: model.to_string(),
246        error: error.to_string(),
247    })
248}
249
250#[cfg(test)]
251mod tests {
252    use super::*;
253    use crate::testing::{
254        DEFAULT_MODEL, agent_config, agent_json_with, fake_spec, has_prompt_file, mcp_json, project, settings_agent,
255    };
256    use aether_core::agent_spec::AgentSpecExposure;
257    use llm::ModelSettings;
258    use serde_json::json;
259
260    fn create_test_catalog(project_root: PathBuf) -> AgentCatalog {
261        let planner = fake_spec("planner", AgentSpecExposure::both());
262        AgentCatalog::new(project_root, vec![planner], None)
263    }
264
265    fn mcp_servers(spec: &AgentSpec) -> Vec<&str> {
266        spec.mcp.servers.keys().map(String::as_str).collect()
267    }
268
269    fn overrides(url: &str) -> ProviderConnectionOverrides {
270        ProviderConnectionOverrides::new(std::collections::BTreeMap::from([(
271            "anthropic".to_string(),
272            llm::ProviderConnectionOverride::url(url),
273        )]))
274    }
275
276    fn base_url(spec: &AgentSpec) -> Option<String> {
277        spec.provider_connections.config_for("anthropic").base_url
278    }
279
280    #[test]
281    fn provider_connections_reach_every_agent_not_just_the_selected_one() {
282        let dir = project();
283        let catalog = AgentCatalog::new(
284            dir.root().to_path_buf(),
285            vec![fake_spec("planner", AgentSpecExposure::both()), fake_spec("worker", AgentSpecExposure::agent_only())],
286            None,
287        )
288        .with_provider_connections(overrides("https://runtime.test"));
289
290        for name in ["planner", "worker"] {
291            assert_eq!(base_url(catalog.get(name).unwrap()).as_deref(), Some("https://runtime.test"), "agent {name}");
292        }
293    }
294
295    #[test]
296    fn runtime_provider_connections_win_over_settings_declared_ones() {
297        let dir = project();
298        let mut declared = fake_spec("planner", AgentSpecExposure::both());
299        declared.provider_connections = overrides("https://from-settings.test");
300
301        let catalog = AgentCatalog::new(dir.root().to_path_buf(), vec![declared], None)
302            .with_provider_connections(overrides("https://runtime.test"));
303
304        assert_eq!(base_url(catalog.get("planner").unwrap()).as_deref(), Some("https://runtime.test"));
305    }
306
307    #[test]
308    fn default_spec_inherits_runtime_provider_connections() {
309        let dir = project();
310        let catalog =
311            AgentCatalog::empty(dir.root().to_path_buf()).with_provider_connections(overrides("https://runtime.test"));
312
313        let spec = catalog.default_spec(&DEFAULT_MODEL.parse().unwrap(), None);
314
315        assert_eq!(spec.name, "__default__");
316        assert_eq!(base_url(&spec).as_deref(), Some("https://runtime.test"));
317    }
318
319    #[test]
320    fn settings_provider_connections_apply_to_explicit_model_specs() {
321        let dir = project().file("PROMPT.md", "Be helpful");
322        let settings = AetherSettings {
323            agents: vec![agent_config("planner")],
324            providers: overrides("https://settings.test"),
325            ..AetherSettings::default()
326        };
327        let catalog = AgentCatalog::from_settings_or_empty(dir.root(), settings).unwrap();
328
329        let spec = catalog.default_spec(&DEFAULT_MODEL.parse().unwrap(), None);
330
331        assert_eq!(base_url(&spec).as_deref(), Some("https://settings.test"));
332    }
333
334    #[test]
335    fn settings_provider_connections_apply_to_fallback_specs_without_agents() {
336        let dir = project();
337        let settings = AetherSettings { providers: overrides("https://settings.test"), ..AetherSettings::default() };
338        let catalog = AgentCatalog::from_settings_or_empty(dir.root(), settings).unwrap();
339
340        let spec = catalog.default_spec(&DEFAULT_MODEL.parse().unwrap(), None);
341
342        assert_eq!(base_url(&spec).as_deref(), Some("https://settings.test"));
343    }
344
345    #[test]
346    fn runtime_provider_connections_override_settings_for_default_specs() {
347        let dir = project();
348        let settings = AetherSettings { providers: overrides("https://settings.test"), ..AetherSettings::default() };
349        let catalog = AgentCatalog::from_settings_or_empty(dir.root(), settings)
350            .unwrap()
351            .with_provider_connections(overrides("https://runtime.test"));
352
353        let spec = catalog.default_spec(&DEFAULT_MODEL.parse().unwrap(), None);
354
355        assert_eq!(base_url(&spec).as_deref(), Some("https://runtime.test"));
356    }
357
358    #[test]
359    fn default_spec_without_overrides_leaves_connections_unset() {
360        let dir = project();
361        let catalog = AgentCatalog::empty(dir.root().to_path_buf());
362
363        let spec = catalog.default_spec(&DEFAULT_MODEL.parse().unwrap(), None);
364
365        assert_eq!(base_url(&spec), None);
366    }
367
368    #[test]
369    fn user_invocable_filters_correctly() {
370        let dir = project();
371        let root = dir.root().to_path_buf();
372        let catalog = AgentCatalog::new(
373            root,
374            vec![
375                fake_spec("planner", AgentSpecExposure::both()),
376                fake_spec("internal", AgentSpecExposure::agent_only()),
377            ],
378            None,
379        );
380
381        let user_invocable: Vec<_> = catalog.user_invocable().collect();
382        assert_eq!(user_invocable.len(), 1);
383        assert_eq!(user_invocable[0].name, "planner");
384    }
385
386    #[test]
387    fn agent_invocable_filters_correctly() {
388        let dir = project();
389        let root = dir.root().to_path_buf();
390        let catalog = AgentCatalog::new(
391            root,
392            vec![
393                fake_spec("planner", AgentSpecExposure::both()),
394                fake_spec("user-only", AgentSpecExposure::user_only()),
395            ],
396            None,
397        );
398
399        let agent_invocable: Vec<_> = catalog.agent_invocable().collect();
400        assert_eq!(agent_invocable.len(), 1);
401        assert_eq!(agent_invocable[0].name, "planner");
402    }
403
404    #[test]
405    fn default_agent_uses_selected_agent() {
406        let dir = project();
407        let catalog = AgentCatalog::new(
408            dir.root().to_path_buf(),
409            vec![fake_spec("first", AgentSpecExposure::both()), fake_spec("second", AgentSpecExposure::both())],
410            Some("second".to_string()),
411        );
412
413        assert_eq!(catalog.default_agent().map(|spec| spec.name.as_str()), Some("second"));
414    }
415
416    #[test]
417    fn default_agent_falls_back_to_first_user_invocable() {
418        let dir = project();
419        let catalog = AgentCatalog::new(
420            dir.root().to_path_buf(),
421            vec![
422                fake_spec("internal", AgentSpecExposure::agent_only()),
423                fake_spec("visible", AgentSpecExposure::user_only()),
424            ],
425            None,
426        );
427
428        assert_eq!(catalog.default_agent().map(|spec| spec.name.as_str()), Some("visible"));
429    }
430
431    #[test]
432    fn get_returns_error_for_missing_agent() {
433        let dir = project();
434        let catalog = create_test_catalog(dir.root().to_path_buf());
435        let result = catalog.get("nonexistent");
436        assert!(matches!(result, Err(SettingsError::AgentNotFound { .. })));
437    }
438
439    #[test]
440    fn agent_rejects_reasoning_effort_unsupported_by_model() {
441        let dir = project().file("PROMPT.md", "Be helpful");
442        let config = AetherSettings {
443            agents: vec![AgentConfig {
444                model: "anthropic:claude-opus-4-6".to_string(),
445                reasoning_effort: Some(llm::ReasoningEffort::Xhigh),
446                ..agent_config("planner")
447            }],
448            ..AetherSettings::default()
449        };
450
451        let error = AgentCatalog::from_settings(dir.root(), config).unwrap_err();
452
453        assert!(matches!(error, SettingsError::InvalidReasoningEffort { .. }));
454    }
455
456    #[test]
457    fn agent_context_window_is_resolved_into_spec() {
458        let dir = project().file("PROMPT.md", "Be helpful");
459
460        let config = AetherSettings {
461            agents: vec![AgentConfig { context_window: Some(200_000), ..agent_config("planner") }],
462            ..AetherSettings::default()
463        };
464
465        let catalog = AgentCatalog::from_settings(dir.root(), config).unwrap();
466        let spec = catalog.resolve("planner").unwrap();
467
468        assert_eq!(spec.context_window, Some(200_000));
469    }
470
471    #[test]
472    fn agent_model_settings_resolve_from_config_json() {
473        let dir = project().file("BASE.md", "Base instructions");
474
475        let json = json!({
476            "agents": [agent_json_with(
477                "judge",
478                "Judge agent",
479                json!({
480                    "prompts": ["BASE.md"],
481                    "modelSettings": { "temperature": 0, "topP": 0.9, "maxTokens": 1024 }
482                }),
483            )]
484        });
485
486        let config: AetherSettings = serde_json::from_value(json).unwrap();
487        let catalog = AgentCatalog::from_settings(dir.root(), config).unwrap();
488        let spec = catalog.resolve("judge").unwrap();
489
490        assert_eq!(
491            spec.model_settings,
492            ModelSettings { temperature: Some(0.0), top_p: Some(0.9), max_tokens: Some(1024) }
493        );
494    }
495
496    #[test]
497    fn agent_context_window_rejects_zero() {
498        let config = AetherSettings {
499            agents: vec![AgentConfig { context_window: Some(0), ..settings_agent("planner", "Planner agent") }],
500            ..AetherSettings::default()
501        };
502
503        let err = AgentCatalog::from_settings(Path::new("/tmp"), config).unwrap_err();
504
505        assert!(matches!(
506            err,
507            SettingsError::InvalidContextWindow { agent, context_window: 0 } if agent == "planner"
508        ));
509    }
510
511    #[test]
512    fn top_level_prompts_are_inherited_when_agent_prompts_are_empty() {
513        let dir = project().file("BASE.md", "Base instructions");
514
515        let config = AetherSettings {
516            prompts: vec![crate::PromptSource::file("BASE.md")],
517            agents: vec![settings_agent("planner", "Planner agent")],
518            ..AetherSettings::default()
519        };
520
521        let catalog = AgentCatalog::from_settings(dir.root(), config).unwrap();
522        let spec = catalog.resolve("planner").unwrap();
523
524        assert!(has_prompt_file(&spec, "BASE.md"));
525    }
526
527    #[test]
528    fn agent_prompts_override_top_level_prompts() {
529        let dir = project().file("BASE.md", "Base instructions").file("AGENT.md", "Agent instructions");
530
531        let config = AetherSettings {
532            prompts: vec![crate::PromptSource::file("BASE.md")],
533            agents: vec![AgentConfig {
534                prompts: vec![crate::PromptSource::file("AGENT.md")],
535                ..settings_agent("planner", "Planner agent")
536            }],
537            ..AetherSettings::default()
538        };
539
540        let catalog = AgentCatalog::from_settings(dir.root(), config).unwrap();
541        let spec = catalog.resolve("planner").unwrap();
542
543        assert!(has_prompt_file(&spec, "AGENT.md"));
544        assert!(!has_prompt_file(&spec, "BASE.md"));
545    }
546
547    #[test]
548    fn top_level_mcps_are_inherited_when_agent_mcps_are_empty() {
549        let dir = project().file("BASE.md", "Base instructions").file("base-mcp.json", mcp_json("base"));
550
551        let config = AetherSettings {
552            prompts: vec![crate::PromptSource::file("BASE.md")],
553            mcps: vec![McpSourceSpec::file("base-mcp.json")],
554            agents: vec![settings_agent("planner", "Planner agent")],
555            ..AetherSettings::default()
556        };
557
558        let catalog = AgentCatalog::from_settings(dir.root(), config).unwrap();
559        let spec = catalog.resolve("planner").unwrap();
560
561        assert_eq!(mcp_servers(&spec), ["base"]);
562    }
563
564    #[test]
565    fn agent_mcps_override_top_level_mcps() {
566        let dir = project()
567            .file("BASE.md", "Base instructions")
568            .file("base-mcp.json", mcp_json("base"))
569            .file("agent-mcp.json", mcp_json("agent"));
570
571        let config = AetherSettings {
572            prompts: vec![crate::PromptSource::file("BASE.md")],
573            mcps: vec![McpSourceSpec::file("base-mcp.json")],
574            agents: vec![AgentConfig {
575                mcps: vec![McpSourceSpec::file("agent-mcp.json")],
576                ..settings_agent("planner", "Planner agent")
577            }],
578            ..AetherSettings::default()
579        };
580
581        let catalog = AgentCatalog::from_settings(dir.root(), config).unwrap();
582        let spec = catalog.resolve("planner").unwrap();
583
584        assert_eq!(mcp_servers(&spec), ["agent"]);
585    }
586
587    #[test]
588    fn unreadable_mcp_config_names_its_path() {
589        let dir = project().file("BASE.md", "Base instructions").file("broken.json", "not json");
590        let config = AetherSettings {
591            prompts: vec![crate::PromptSource::file("BASE.md")],
592            mcps: vec![McpSourceSpec::file("broken.json")],
593            agents: vec![settings_agent("planner", "Planner agent")],
594            ..AetherSettings::default()
595        };
596
597        let error = AgentCatalog::from_settings(dir.root(), config).unwrap_err();
598
599        assert!(matches!(error, SettingsError::McpConfig { ref path, .. } if path == "broken.json"), "{error}");
600    }
601
602    #[test]
603    fn missing_top_level_and_agent_prompts_still_errors() {
604        let config =
605            AetherSettings { agents: vec![settings_agent("planner", "Planner agent")], ..AetherSettings::default() };
606
607        let err = AgentCatalog::from_settings(Path::new("/tmp"), config).unwrap_err();
608
609        assert!(matches!(err, SettingsError::NoPromptsDeclared { agent } if agent == "planner"));
610    }
611
612    #[test]
613    fn resolve_missing_agent_returns_error() {
614        let dir = project();
615        let catalog = create_test_catalog(dir.root().to_path_buf());
616        let result = catalog.resolve("missing");
617        assert!(matches!(result, Err(SettingsError::AgentNotFound { .. })));
618    }
619
620    #[test]
621    fn resolve_preserves_agent_mcp() {
622        let dir = project();
623        let mut planner = fake_spec("planner", AgentSpecExposure::both());
624        planner.mcp = McpConfig::from_json(&mcp_json("agent")).unwrap();
625
626        let catalog = AgentCatalog::new(dir.root().to_path_buf(), vec![planner], None);
627
628        let spec = catalog.resolve("planner").unwrap();
629        assert_eq!(mcp_servers(&spec), ["agent"]);
630    }
631
632    #[test]
633    fn resolve_no_mcp_config_is_valid() {
634        let dir = project();
635        let catalog =
636            AgentCatalog::new(dir.root().to_path_buf(), vec![fake_spec("planner", AgentSpecExposure::both())], None);
637
638        let spec = catalog.resolve("planner").unwrap();
639        assert!(spec.mcp.is_empty());
640    }
641}
aether_project/agent_catalog.rs

aether_project/
agent_catalog.rs
