compoundingtech
diff --git a/‎crates/agent-spec/src/spec.rs‎
Lines changed: 128 additions & 4 deletions b/‎crates/agent-spec/src/spec.rs‎
Lines changed: 128 additions & 4 deletions
diff --git a/‎crates/agent-spec/tests/discovery.rs‎
Lines changed: 166 additions & 12 deletions b/‎crates/agent-spec/tests/discovery.rs‎
Lines changed: 166 additions & 12 deletions
@@ -256,11 +256,21 @@ struct ResourceDescriptor {
 impl Resource {
     /// Construct a descriptor after enforcing the same invariants as catalog parsing.
     pub fn new(name: String, uri: String, reason: String) -> Result<Self, String> {
-        if name.is_empty() {
-            return Err("resource binding name cannot be empty".into());
+        if name.is_empty()
+            || name.len() > 200
+            || name.trim() != name
+            || name.chars().any(char::is_control)
+        {
+            return Err(
+                "resource binding name must be 1..=200 bytes without surrounding whitespace or controls"
+                    .into(),
+            );
+        }
+        if name == "declaration" {
+            return Err("resource binding name 'declaration' is reserved by resync".into());
         }
-        validate_absolute_uri(&uri).map_err(|reason| {
-            format!("resource binding '{name}' `uri` must be an exact absolute URI: {reason}")
+        validate_resource_uri(&uri).map_err(|reason| {
+            format!("resource binding '{name}' `uri` must be an exact absolute URI or a catalog-relative path: {reason}")
         })?;
         validate_resource_explanation(&name, "reason", &reason)?;
         Ok(Self {
@@ -585,6 +595,10 @@ fn validate_stream_name(identity: &str, name: &str) -> anyhow::Result<()> {
             && !name.ends_with('-'),
         "agent '{identity}' stream name '{name}' must match [a-z0-9]([a-z0-9-]*[a-z0-9])?"
     );
+    anyhow::ensure!(
+        name != "resync",
+        "agent '{identity}' stream name '{name}' is reserved for built-in resync events"
+    );
     Ok(())
 }
 
@@ -764,6 +778,87 @@ fn validate_resource_explanation(name: &str, field: &str, value: &str) -> Result
     Ok(())
 }
 
+/// A resource URI is either an exact absolute URI (any scheme) or a catalog-relative path with no
+/// scheme at all, resolved by the consumer against the declaration directory. Relative carriers
+/// are an st2 extension pending canonical Agent Spec adoption (see 06-resync).
+fn validate_resource_uri(uri: &str) -> Result<(), &'static str> {
+    if let Some(colon) = uri.find(':') {
+        let first_separator = uri.find(|character| matches!(character, '/' | '\\'));
+        if first_separator.is_none_or(|separator| colon < separator) {
+            return validate_absolute_uri(uri);
+        }
+    }
+    if uri.is_empty() {
+        return Err("catalog-relative uri must be a non-empty relative path");
+    }
+    let decoded = decode_percent_path(uri)?;
+    if decoded.starts_with('/') || decoded.split('/').any(|part| part == "..") {
+        return Err(
+            "catalog-relative uri must be a relative path without parent (`..`) components",
+        );
+    }
+    Ok(())
+}
+
+/// Decode filesystem-path percent escapes without allowing an escape to change path segmentation.
+///
+/// Consumers may apply additional policy to the decoded path (for example, catalog-relative
+/// resources reject every parent component). This shared boundary rejects bytes that cannot name
+/// the same UTF-8 filesystem path the resource URI visibly denotes.
+pub fn decode_percent_path(encoded_path: &str) -> Result<String, &'static str> {
+    let bytes = encoded_path.as_bytes();
+    let mut decoded = Vec::with_capacity(bytes.len());
+    let mut component_start = 0;
+    let mut component_had_escape = false;
+    let mut offset = 0;
+    while offset < bytes.len() {
+        if bytes[offset] == b'/' {
+            if component_had_escape && decoded[component_start..] == *b".." {
+                return Err("path contains an encoded parent (`..`) component");
+            }
+            decoded.push(b'/');
+            component_start = decoded.len();
+            component_had_escape = false;
+            offset += 1;
+            continue;
+        }
+        if bytes[offset] != b'%' {
+            decoded.push(bytes[offset]);
+            offset += 1;
+            continue;
+        }
+        let Some(high) = bytes.get(offset + 1).and_then(|byte| hex_digit(*byte)) else {
+            return Err("path contains an invalid percent escape");
+        };
+        let Some(low) = bytes.get(offset + 2).and_then(|byte| hex_digit(*byte)) else {
+            return Err("path contains an invalid percent escape");
+        };
+        let byte = (high << 4) | low;
+        if matches!(byte, b'/' | b'\\') {
+            return Err("path contains an encoded separator");
+        }
+        if byte == b'\0' {
+            return Err("path decodes to NUL");
+        }
+        decoded.push(byte);
+        component_had_escape = true;
+        offset += 3;
+    }
+    if component_had_escape && decoded[component_start..] == *b".." {
+        return Err("path contains an encoded parent (`..`) component");
+    }
+    String::from_utf8(decoded).map_err(|_| "percent-decoded path is not valid UTF-8")
+}
+
+fn hex_digit(byte: u8) -> Option<u8> {
+    match byte {
+        b'0'..=b'9' => Some(byte - b'0'),
+        b'a'..=b'f' => Some(byte - b'a' + 10),
+        b'A'..=b'F' => Some(byte - b'A' + 10),
+        _ => None,
+    }
+}
+
 fn validate_absolute_uri(uri: &str) -> Result<(), &'static str> {
     let Some(colon) = uri.find(':') else {
         return Err("missing scheme");
@@ -1360,6 +1455,35 @@ mod tests {
         assert!(parse_duration("").is_err());
     }
 
+    #[test]
+    fn catalog_relative_uris_share_filesystem_safe_percent_decoding() {
+        for uri in [
+            "report..md",
+            "reports/.../goal.md",
+            "reports/%2Ereport.md",
+            "reports/child..name/goal.md",
+            "reports/with%20space/%E2%82%AC.md",
+        ] {
+            assert_eq!(validate_resource_uri(uri), Ok(()), "{uri}");
+        }
+
+        for uri in [
+            "..",
+            "../goal.md",
+            "reports/../goal.md",
+            "%2e%2e/goal.md",
+            "reports/%2E%2e/goal.md",
+            "reports%2f..%2fgoal.md",
+            "reports/encoded%2Fseparator",
+            "reports/encoded%5cseparator",
+            "reports/a%00b",
+            "reports/%FF.md",
+            "reports/bad%escape",
+        ] {
+            assert!(validate_resource_uri(uri).is_err(), "{uri}");
+        }
+    }
+
     #[test]
     fn absolute_uri_syntax_accepts_rfc3986_characters_without_normalizing() {
         for uri in [
 
@@ -1134,6 +1134,30 @@ fn resource_explanation_byte_bounds_are_enforced() {
     );
 }
 
+#[test]
+fn resource_binding_names_and_scheme_candidates_fail_loudly() {
+    for name in [
+        " declaration".to_owned(),
+        "declaration".to_owned(),
+        "line\nbreak".to_owned(),
+        "x".repeat(201),
+    ] {
+        assert!(
+            Resource::new(name.clone(), "issue://one".into(), "Task.".into()).is_err(),
+            "invalid binding name was accepted: {name:?}"
+        );
+    }
+    assert!(
+        Resource::new(
+            "work".into(),
+            "_github://org/repo".into(),
+            "Task.".into(),
+        )
+        .is_err(),
+        "a malformed scheme prefix must not become a catalog-relative path"
+    );
+}
+
 #[test]
 fn malformed_resource_envelopes_are_rejected_without_defining_downstream_types() {
     let tmp = tempfile::tempdir().unwrap();
@@ -1148,10 +1172,6 @@ fn malformed_resource_envelopes_are_rejected_without_defining_downstream_types()
             r#"resource "work" _tag="issue" uri="issue://example/1" reason="Task.""#,
         ),
         ("missing-uri", r#"resource "work" reason="Task.""#),
-        (
-            "relative-uri",
-            r#"resource "work" uri="./issue/1" reason="Task.""#,
-        ),
         (
             "policy",
             r#"resource "work" uri="issue://example/1" reason="Task." required=#true"#,
@@ -1170,7 +1190,7 @@ fn malformed_resource_envelopes_are_rejected_without_defining_downstream_types()
 
     let found = discover(tmp.path());
     assert!(found.specs.is_empty(), "{:?}", found.specs);
-    assert_eq!(found.errors.len(), 6, "{:?}", found.errors);
+    assert_eq!(found.errors.len(), 5, "{:?}", found.errors);
     let errors = found
         .errors
         .iter()
@@ -1186,12 +1206,6 @@ fn malformed_resource_envelopes_are_rejected_without_defining_downstream_types()
             .iter()
             .any(|error| error.contains("unsupported property `_tag`"))
     );
-    assert!(
-        errors
-            .iter()
-            .any(|error| error.contains("needs string `uri`"))
-    );
-    assert!(errors.iter().any(|error| error.contains("absolute URI")));
     assert!(
         errors
             .iter()
@@ -1204,6 +1218,146 @@ fn malformed_resource_envelopes_are_rejected_without_defining_downstream_types()
     );
 }
 
+#[test]
+fn catalog_relative_resource_uris_are_an_st2_extension_resolved_against_the_declaration_dir() {
+    // Catalog-relative carrier paths are an st2 extension pending canonical Agent Spec adoption
+    // (see docs/vrs/06-resync): accepted here, resolved by the consumer against the declaration
+    // directory.
+    let tmp = tempfile::tempdir().unwrap();
+    write(
+        tmp.path(),
+        "agents/h/relative/agent.kdl",
+        r#"agent "relative" {
+  host "h"
+  command "true"
+  resource "work" uri="resources/goal.md" reason="Task."
+}"#,
+    );
+    let found = discover(tmp.path());
+    assert!(
+        found.specs.iter().any(|spec| spec.identity == "relative"
+            && spec
+                .resources
+                .iter()
+                .any(|r| r.uri() == "resources/goal.md")),
+        "{:?}",
+        found.errors
+    );
+    let descriptor: Resource =
+        serde_json::from_str(r#"{"name":"work","uri":"resources/goal.md","reason":"Task."}"#)
+            .expect("catalog-relative uri is valid");
+    assert_eq!(descriptor.uri(), "resources/goal.md");
+
+    let absolute = Resource::new(
+        "work".into(),
+        "/etc/absolute".into(),
+        "Still refused.".into(),
+    );
+    assert!(absolute.is_err(), "absolute paths must keep a scheme");
+}
+
+#[test]
+fn resource_percent_paths_are_validated_consistently_across_public_inputs() {
+    let tmp = tempfile::tempdir().unwrap();
+    write(
+        tmp.path(),
+        "agents/h/valid-kdl/agent.kdl",
+        r#"agent "valid-kdl" {
+  host "h"
+  command "true"
+  resource "work" uri="resources/with%20space.md" reason="Task."
+}"#,
+    );
+    write(
+        tmp.path(),
+        "agents/h/invalid-kdl/agent.kdl",
+        r#"agent "invalid-kdl" {
+  host "h"
+  command "true"
+  resource "work" uri="resources/a%00b" reason="Task."
+}"#,
+    );
+    write(
+        tmp.path(),
+        "agents/h/valid-json/agent.json",
+        r#"{
+  "identity": "valid-json",
+  "host": "h",
+  "command": "true",
+  "resource": {"work": {"uri": "resources/with%20space.md", "reason": "Task."}}
+}"#,
+    );
+    write(
+        tmp.path(),
+        "agents/h/invalid-json/agent.json",
+        r#"{
+  "identity": "invalid-json",
+  "host": "h",
+  "command": "true",
+  "resource": {"work": {"uri": "resources/encoded%2Fseparator", "reason": "Task."}}
+}"#,
+    );
+    write(
+        tmp.path(),
+        "agents/h/valid-toml/agent.toml",
+        r#"identity = "valid-toml"
+host = "h"
+command = "true"
+[resource.work]
+uri = "resources/with%20space.md"
+reason = "Task."
+"#,
+    );
+    write(
+        tmp.path(),
+        "agents/h/invalid-toml/agent.toml",
+        r#"identity = "invalid-toml"
+host = "h"
+command = "true"
+[resource.work]
+uri = "resources/%FF.md"
+reason = "Task."
+"#,
+    );
+
+    let found = discover(tmp.path());
+    let identities = found
+        .specs
+        .iter()
+        .map(|spec| spec.identity.as_str())
+        .collect::<Vec<_>>();
+    assert_eq!(
+        identities,
+        vec!["valid-json", "valid-kdl", "valid-toml"],
+        "{:?}",
+        found.errors
+    );
+    assert_eq!(found.errors.len(), 3, "{:?}", found.errors);
+
+    let valid: Resource = serde_json::from_str(
+        r#"{"name":"work","uri":"resources/with%20space/%E2%82%AC.md","reason":"Task."}"#,
+    )
+    .unwrap();
+    assert_eq!(
+        valid.uri(),
+        "resources/with%20space/%E2%82%AC.md",
+        "validation must preserve the URI identity instead of normalizing it"
+    );
+    for uri in [
+        "resources/a%00b",
+        "resources/encoded%2Fseparator",
+        "resources/encoded%5cseparator",
+        "resources/%FF.md",
+        "resources/%2e%2e/goal.md",
+    ] {
+        let descriptor = format!(r#"{{"name":"work","uri":"{uri}","reason":"Task."}}"#);
+        assert!(
+            serde_json::from_str::<Resource>(&descriptor).is_err(),
+            "{uri}"
+        );
+    }
+}
+
 #[test]
 fn duplicate_json_resource_names_are_rejected_instead_of_last_write_winning() {
     let tmp = tempfile::tempdir().unwrap();
@@ -1233,7 +1387,7 @@ fn duplicate_json_resource_names_are_rejected_instead_of_last_write_winning() {
 fn public_resource_json_deserialization_enforces_the_catalog_invariants() {
     for descriptor in [
         r#"{"name":"","uri":"issue://one","reason":"Task."}"#,
-        r#"{"name":"work","uri":"./relative","reason":"Task."}"#,
+        r#"{"name":"work","uri":"/etc/absolute","reason":"Task."}"#,
         r#"{"name":"work","uri":"issue://one","reason":"Task.","_tag":"issue"}"#,
         r#"{"name":"work","uri":"issue://one","reason":"Task.","required":true}"#,
     ] {