feat(acp-nats-agent): add server-side ACP agent framework

Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>

Author: yordis

rsworkspace/crates/acp-nats-agent/Cargo.toml

@@ -0,0 +1,36 @@
+[package]
+name = "acp-nats-agent"
+version = "0.0.1"
+edition = "2024"
+
+[lints]
+workspace = true
+
+[dependencies]
+acp-nats = { workspace = true }
+agent-client-protocol = { workspace = true, features = [
+    "unstable_auth_methods",
+    "unstable_boolean_config",
+    "unstable_cancel_request",
+    "unstable_message_id",
+    "unstable_session_close",
+    "unstable_session_fork",
+    "unstable_session_model",
+    "unstable_session_resume",
+    "unstable_session_usage",
+] }
+async-nats = { workspace = true }
+async-trait = { workspace = true }
+bytes = { workspace = true }
+futures = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+tokio = { workspace = true, features = ["rt", "macros", "sync"] }
+tracing = { workspace = true }
+trogon-nats = { workspace = true }
+trogon-std = { workspace = true }
+
+[dev-dependencies]
+tokio = { workspace = true, features = ["test-util"] }
+trogon-nats = { workspace = true, features = ["test-support"] }
+trogon-std = { workspace = true, features = ["test-support"] }

rsworkspace/crates/acp-nats-agent/src/config.rs

@@ -0,0 +1,15 @@
+use acp_nats::AcpPrefix;
+
+pub struct AgentServerConfig {
+    acp_prefix: AcpPrefix,
+}
+
+impl AgentServerConfig {
+    pub fn new(acp_prefix: AcpPrefix) -> Self {
+        Self { acp_prefix }
+    }
+
+    pub fn acp_prefix(&self) -> &AcpPrefix {
+        &self.acp_prefix
+    }
+}

rsworkspace/crates/acp-nats-agent/src/dispatch.rs

@@ -0,0 +1,275 @@
+use acp_nats::AcpSessionId;
+use acp_nats::ext_method_name::ExtMethodName;
+
+const AGENT_MARKER: &str = ".agent.";
+const EXT_PREFIX: &str = "agent.ext.";
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AgentMethod {
+    Initialize,
+    Authenticate,
+    SessionNew,
+    SessionList,
+    SessionLoad,
+    SessionPrompt,
+    SessionCancel,
+    SessionSetMode,
+    SessionSetConfigOption,
+    SessionSetModel,
+    SessionFork,
+    SessionResume,
+    SessionClose,
+    Ext(ExtMethodName),
+}
+
+impl AgentMethod {
+    pub fn is_session_scoped(&self) -> bool {
+        !matches!(
+            self,
+            Self::Initialize
+                | Self::Authenticate
+                | Self::SessionNew
+                | Self::SessionList
+                | Self::Ext(_)
+        )
+    }
+
+    fn from_suffix(suffix: &str) -> Option<Self> {
+        match suffix {
+            "agent.initialize" => Some(Self::Initialize),
+            "agent.authenticate" => Some(Self::Authenticate),
+            "agent.session.new" => Some(Self::SessionNew),
+            "agent.session.list" => Some(Self::SessionList),
+            "agent.session.load" => Some(Self::SessionLoad),
+            "agent.session.prompt" => Some(Self::SessionPrompt),
+            "agent.session.cancel" => Some(Self::SessionCancel),
+            "agent.session.set_mode" => Some(Self::SessionSetMode),
+            "agent.session.set_config_option" => Some(Self::SessionSetConfigOption),
+            "agent.session.set_model" => Some(Self::SessionSetModel),
+            "agent.session.fork" => Some(Self::SessionFork),
+            "agent.session.resume" => Some(Self::SessionResume),
+            "agent.session.close" => Some(Self::SessionClose),
+            other => {
+                let ext_name = other.strip_prefix(EXT_PREFIX)?;
+                Some(Self::Ext(ExtMethodName::new(ext_name).ok()?))
+            }
+        }
+    }
+}
+
+#[derive(Debug)]
+pub struct ParsedAgentSubject {
+    pub session_id: Option<AcpSessionId>,
+    pub method: AgentMethod,
+}
+
+pub fn parse_agent_subject(subject: &str) -> Option<ParsedAgentSubject> {
+    for (agent_byte_pos, _) in subject.match_indices(AGENT_MARKER) {
+        let suffix = &subject[agent_byte_pos + 1..];
+        let method = match AgentMethod::from_suffix(suffix) {
+            Some(m) => m,
+            None => continue,
+        };
+
+        let session_id = if method.is_session_scoped() {
+            let before_agent = &subject[..agent_byte_pos];
+            let session_dot = before_agent.rfind('.')?;
+            let raw = &before_agent[session_dot + 1..];
+            Some(AcpSessionId::new(raw).ok()?)
+        } else {
+            None
+        };
+
+        return Some(ParsedAgentSubject { session_id, method });
+    }
+
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_initialize() {
+        let parsed = parse_agent_subject("acp.agent.initialize").unwrap();
+        assert!(parsed.session_id.is_none());
+        assert_eq!(parsed.method, AgentMethod::Initialize);
+    }
+
+    #[test]
+    fn parse_authenticate() {
+        let parsed = parse_agent_subject("acp.agent.authenticate").unwrap();
+        assert!(parsed.session_id.is_none());
+        assert_eq!(parsed.method, AgentMethod::Authenticate);
+    }
+
+    #[test]
+    fn parse_session_new() {
+        let parsed = parse_agent_subject("acp.agent.session.new").unwrap();
+        assert!(parsed.session_id.is_none());
+        assert_eq!(parsed.method, AgentMethod::SessionNew);
+    }
+
+    #[test]
+    fn parse_session_list() {
+        let parsed = parse_agent_subject("acp.agent.session.list").unwrap();
+        assert!(parsed.session_id.is_none());
+        assert_eq!(parsed.method, AgentMethod::SessionList);
+    }
+
+    #[test]
+    fn parse_session_load() {
+        let parsed = parse_agent_subject("acp.s1.agent.session.load").unwrap();
+        assert_eq!(parsed.session_id.unwrap().as_str(), "s1");
+        assert_eq!(parsed.method, AgentMethod::SessionLoad);
+    }
+
+    #[test]
+    fn parse_session_prompt() {
+        let parsed = parse_agent_subject("acp.s1.agent.session.prompt").unwrap();
+        assert_eq!(parsed.session_id.unwrap().as_str(), "s1");
+        assert_eq!(parsed.method, AgentMethod::SessionPrompt);
+    }
+
+    #[test]
+    fn parse_session_cancel() {
+        let parsed = parse_agent_subject("acp.s1.agent.session.cancel").unwrap();
+        assert_eq!(parsed.session_id.unwrap().as_str(), "s1");
+        assert_eq!(parsed.method, AgentMethod::SessionCancel);
+    }
+
+    #[test]
+    fn parse_session_set_mode() {
+        let parsed = parse_agent_subject("acp.s1.agent.session.set_mode").unwrap();
+        assert_eq!(parsed.session_id.unwrap().as_str(), "s1");
+        assert_eq!(parsed.method, AgentMethod::SessionSetMode);
+    }
+
+    #[test]
+    fn parse_session_set_config_option() {
+        let parsed = parse_agent_subject("acp.s1.agent.session.set_config_option").unwrap();
+        assert_eq!(parsed.session_id.unwrap().as_str(), "s1");
+        assert_eq!(parsed.method, AgentMethod::SessionSetConfigOption);
+    }
+
+    #[test]
+    fn parse_session_set_model() {
+        let parsed = parse_agent_subject("acp.s1.agent.session.set_model").unwrap();
+        assert_eq!(parsed.session_id.unwrap().as_str(), "s1");
+        assert_eq!(parsed.method, AgentMethod::SessionSetModel);
+    }
+
+    #[test]
+    fn parse_session_fork() {
+        let parsed = parse_agent_subject("acp.s1.agent.session.fork").unwrap();
+        assert_eq!(parsed.session_id.unwrap().as_str(), "s1");
+        assert_eq!(parsed.method, AgentMethod::SessionFork);
+    }
+
+    #[test]
+    fn parse_session_resume() {
+        let parsed = parse_agent_subject("acp.s1.agent.session.resume").unwrap();
+        assert_eq!(parsed.session_id.unwrap().as_str(), "s1");
+        assert_eq!(parsed.method, AgentMethod::SessionResume);
+    }
+
+    #[test]
+    fn parse_session_close() {
+        let parsed = parse_agent_subject("acp.s1.agent.session.close").unwrap();
+        assert_eq!(parsed.session_id.unwrap().as_str(), "s1");
+        assert_eq!(parsed.method, AgentMethod::SessionClose);
+    }
+
+    #[test]
+    fn parse_ext_method() {
+        let parsed = parse_agent_subject("acp.agent.ext.my_tool").unwrap();
+        assert!(parsed.session_id.is_none());
+        assert_eq!(parsed.method, AgentMethod::Ext(ExtMethodName::new("my_tool").unwrap()));
+    }
+
+    #[test]
+    fn parse_ext_dotted_namespace() {
+        let parsed = parse_agent_subject("acp.agent.ext.vendor.operation").unwrap();
+        assert!(parsed.session_id.is_none());
+        assert_eq!(
+            parsed.method,
+            AgentMethod::Ext(ExtMethodName::new("vendor.operation").unwrap())
+        );
+    }
+
+    #[test]
+    fn parse_custom_prefix() {
+        let parsed = parse_agent_subject("myapp.agent.initialize").unwrap();
+        assert!(parsed.session_id.is_none());
+        assert_eq!(parsed.method, AgentMethod::Initialize);
+    }
+
+    #[test]
+    fn parse_multi_part_prefix() {
+        let parsed = parse_agent_subject("my.multi.prefix.s1.agent.session.load").unwrap();
+        assert_eq!(parsed.session_id.unwrap().as_str(), "s1");
+        assert_eq!(parsed.method, AgentMethod::SessionLoad);
+    }
+
+    #[test]
+    fn parse_empty_returns_none() {
+        assert!(parse_agent_subject("").is_none());
+    }
+
+    #[test]
+    fn parse_no_agent_marker_returns_none() {
+        assert!(parse_agent_subject("acp.client.session.update").is_none());
+    }
+
+    #[test]
+    fn parse_unknown_method_returns_none() {
+        assert!(parse_agent_subject("acp.agent.unknown.method").is_none());
+    }
+
+    #[test]
+    fn parse_invalid_session_id_returns_none() {
+        assert!(parse_agent_subject("acp.sess*ion.agent.session.load").is_none());
+    }
+
+    #[test]
+    fn parse_ext_empty_name_returns_none() {
+        assert!(parse_agent_subject("acp.agent.ext.").is_none());
+    }
+
+    #[test]
+    fn parse_ext_wildcard_returns_none() {
+        assert!(parse_agent_subject("acp.agent.ext.*").is_none());
+    }
+
+    #[test]
+    fn parse_multi_dot_prefix_global_method_has_no_session() {
+        let parsed = parse_agent_subject("my.multi.agent.initialize").unwrap();
+        assert!(parsed.session_id.is_none());
+        assert_eq!(parsed.method, AgentMethod::Initialize);
+    }
+
+    #[test]
+    fn parse_prefix_containing_agent_word() {
+        let parsed = parse_agent_subject("org.agent.app.agent.initialize").unwrap();
+        assert!(parsed.session_id.is_none());
+        assert_eq!(parsed.method, AgentMethod::Initialize);
+    }
+
+    #[test]
+    fn parse_ext_method_containing_agent_segment() {
+        let parsed = parse_agent_subject("acp.agent.ext.agent.foo").unwrap();
+        assert!(parsed.session_id.is_none());
+        assert_eq!(
+            parsed.method,
+            AgentMethod::Ext(ExtMethodName::new("agent.foo").unwrap())
+        );
+    }
+
+    #[test]
+    fn parse_multi_dot_prefix_session_scoped() {
+        let parsed = parse_agent_subject("my.multi.s1.agent.session.prompt").unwrap();
+        assert_eq!(parsed.session_id.unwrap().as_str(), "s1");
+        assert_eq!(parsed.method, AgentMethod::SessionPrompt);
+    }
+}

rsworkspace/crates/acp-nats-agent/src/lib.rs

@@ -0,0 +1,6 @@
+mod config;
+mod dispatch;
+mod serve;
+
+pub use config::AgentServerConfig;
+pub use serve::AgentServer;