fix(catalog): preserve colocated agent declarations

Author: schickling

crates/agent-spec/src/discovery.rs

@@ -10,7 +10,9 @@
 use std::fs;
 use std::path::{Component, Path, PathBuf};
 
-use crate::declared::{DeclaredParse, parse_declared_document};
+use crate::declared::{
+    DeclaredDiagnosticCode, DeclaredParse, parse_declared_document,
+};
 use crate::spec::{AgentSpec, RawSpec};
 
 /// The result of walking a catalog folder. Sorted + deterministic.
@@ -361,7 +363,8 @@ fn parse_raw_file_with_declaration(path: &Path) -> ParsedRawFile {
         }
     };
     if ext == "kdl" {
-        let declaration = parse_declared_document(path, &text);
+        let mut declaration = parse_declared_document(path, &text);
+        admit_catalog_envelope_nodes(path, &mut declaration);
         let is_adjacent_kdl = declaration
             .document
             .as_ref()
@@ -411,6 +414,29 @@ fn parse_raw_file_with_declaration(path: &Path) -> ParsedRawFile {
     }
 }
 
+/// `catalog.kdl` is a shared envelope: st2 owns its `catalog`/`profile` nodes while Agent Spec
+/// discovery owns any colocated `agent` nodes. Suppress only the top-level diagnostics attached to
+/// those two explicitly admitted envelope node kinds; every agent-shape diagnostic and every other
+/// unexpected node remains an error.
+fn admit_catalog_envelope_nodes(path: &Path, declaration: &mut DeclaredParse) {
+    if path.file_name().and_then(|name| name.to_str()) != Some("catalog.kdl") {
+        return;
+    }
+    let Some(document) = declaration.document.as_ref() else {
+        return;
+    };
+    let admitted_spans = document
+        .nodes
+        .iter()
+        .filter(|node| matches!(node.name.as_str(), "catalog" | "profile"))
+        .map(|node| node.span)
+        .collect::<Vec<_>>();
+    declaration.diagnostics.retain(|diagnostic| {
+        diagnostic.code != DeclaredDiagnosticCode::UnexpectedTopLevelNode
+            || !admitted_spans.contains(&diagnostic.span)
+    });
+}
+
 /// Parse one file into `(specs, warnings)`. TOML/JSON yield 0-or-1 spec; KDL yields one per `agent`
 /// node. Non-spec files yield an empty vec; a malformed file is an `Err` (collected, never fatal).
 fn load_specs(

src/resync.rs

@@ -1351,7 +1351,7 @@ mod tests {
         let current_path = resources.join("current-goal.md");
         std::fs::write(&old_path, "pending bytes").unwrap();
         std::fs::write(&current_path, "current rebound bytes").unwrap();
-        let current = watch_set_for(&discover(root.path()), "alias");
+        let current = watch_set_for(&discover(root.path()), "alias", &Default::default());
         let declaration = current.declaration_path.clone();
         let mut worker = Worker {
             root: root.path().to_path_buf(),
@@ -1364,6 +1364,7 @@ mod tests {
                     seat_id: None,
                     label: "goal".to_owned(),
                     class: CarrierClass::Immediate,
+                    containment_root: None,
                     digest: Some("old-digest".to_owned()),
                     pending_transition: None,
                     dirty: true,
@@ -1428,6 +1429,7 @@ mod tests {
                     seat_id: None,
                     label: "goal".to_owned(),
                     class: CarrierClass::Immediate,
+                    containment_root: None,
                     digest: read_digest(&old_path, None),
                     pending_transition: None,
                     dirty: false,
@@ -1446,6 +1448,7 @@ mod tests {
                 label: "goal".to_owned(),
                 path: new_path.clone(),
                 class: CarrierClass::Immediate,
+                containment_root: None,
             }],
         }]));
 
@@ -1475,6 +1478,7 @@ mod tests {
                     seat_id: None,
                     label: "spec".to_owned(),
                     class: CarrierClass::Immediate,
+                    containment_root: None,
                     digest: read_digest(&carrier, None),
                     pending_transition: None,
                     dirty: true,
@@ -1493,6 +1497,7 @@ mod tests {
                     label: "spec".to_owned(),
                     path: carrier.clone(),
                     class,
+                    containment_root: None,
                 }],
             }])
         };

tests/catalog_config.rs

@@ -117,6 +117,39 @@ fn declaring_a_root_does_not_turn_the_catalog_into_a_single_file_spec() {
     );
 }
 
+#[test]
+fn catalog_profile_and_agent_nodes_share_catalog_kdl_without_hiding_the_agent() {
+    let catalog = tempfile::tempdir().unwrap();
+    fs::write(
+        catalog.path().join("catalog.kdl"),
+        r#"catalog { pty-root "pty" }
+profile "dev.example.goal" { wasm "resolver.wasm"; class "immediate" }
+agent "worker" { host "hetz"; command "true" }
+"#,
+    )
+    .unwrap();
+
+    let discovered = st2::discover_strict(catalog.path());
+    assert!(discovered.errors.is_empty(), "{:?}", discovered.errors);
+    assert!(discovered.warnings.is_empty(), "{:?}", discovered.warnings);
+    assert_eq!(discovered.specs.len(), 1);
+    assert_eq!(discovered.specs[0].identity, "worker");
+    assert_eq!(discovered.specs[0].host.as_deref(), Some("hetz"));
+    assert!(
+        discovered.declarations[0]
+            .parse
+            .as_ref()
+            .is_some_and(agent_spec::DeclaredParse::is_valid),
+        "the shared catalog envelope must retain a valid agent declaration parse"
+    );
+
+    let config = st2::catalog::load(catalog.path()).expect("catalog and profile nodes parse");
+    assert_eq!(config.pty_root.as_deref(), Some("pty"));
+    assert_eq!(config.profiles.len(), 1);
+    assert_eq!(config.profiles[0].scheme, "dev.example.goal");
+    assert_eq!(config.profiles[0].wasm, "resolver.wasm");
+}
+
 /// A mistyped field resolves back to `<catalog>/pty`, which is the split registry this declaration
 /// exists to prevent — so it fails the gate instead of degrading quietly.
 #[test]