feat: add post_download_hook script support for agent types (#2573)

* feat: add post_download_hook script support for agent types

Author: vjripoll

CHANGELOG.md

@@ -18,6 +18,7 @@ Remember that the keywords that you can use are the following:
 - Hardens service restart policies on Linux and Windows (systemd rate limiting: 5 restarts max in 60s) to prevent
   crash-looping from saturating CPU.
 - Added support for remote agent type retrieval.
+- add post-download script support for OCI packages.
 
 ## v1.17.0 - 2026-06-16
 

agent-control/src/agent_control/version_updater/on_host.rs

@@ -136,6 +136,7 @@ where
                 version: new_version,
                 public_key_url: Some(self.pub_key_url.clone()),
             },
+            post_download_hook: None,
         }
     }
 }

agent-control/src/agent_type/definition.rs

@@ -328,6 +328,7 @@ pub fn include_packages_variables(
         let package_data = PackageData {
             id: package_id.to_string(),
             oci: package.download.oci.clone(),
+            post_download_hook: package.post_download_hook.clone(),
         };
         let path =
             get_package_path(Path::new(remote_dir), &agent_id, &package_data).map_err(|e| {

agent-control/src/agent_type/runtime_config/on_host.rs

@@ -169,6 +169,7 @@ mod tests {
                     )),
                 },
             },
+            post_download_hook: None,
         };
 
         let expected_packages = HashMap::from([

agent-control/src/agent_type/runtime_config/on_host/executable.rs

@@ -36,17 +36,10 @@ impl Templateable for Executable {
     type Output = rendered::Executable;
 
     fn template_with(self, variables: &Variables) -> Result<Self::Output, AgentTypeError> {
-        let args: Vec<String> = self
-            .args
-            .0
-            .into_iter()
-            .map(|arg| arg.template_with(variables))
-            .collect::<Result<Vec<String>, AgentTypeError>>()?;
-
         Ok(Self::Output {
             id: self.id.template_with(variables)?,
             path: self.path.template_with(variables)?,
-            args: rendered::Args(args),
+            args: self.args.template_with(variables)?,
             env: self.env.template_with(variables)?,
             restart_policy: self.restart_policy.template_with(variables)?,
         })
@@ -56,6 +49,18 @@ impl Templateable for Executable {
 #[derive(Debug, Default, Deserialize, Clone, PartialEq)]
 pub struct Args(pub Vec<TemplateableValue<String>>);
 
+impl Templateable for Args {
+    type Output = rendered::Args;
+
+    fn template_with(self, variables: &Variables) -> Result<Self::Output, AgentTypeError> {
+        self.0
+            .into_iter()
+            .map(|arg| arg.template_with(variables))
+            .collect::<Result<Vec<String>, AgentTypeError>>()
+            .map(rendered::Args)
+    }
+}
+
 #[derive(Debug, Default, Deserialize, Clone, PartialEq)]
 pub struct Env(pub(super) HashMap<String, TemplateableValue<String>>);
 

agent-control/src/agent_type/runtime_config/on_host/package.rs

@@ -2,6 +2,7 @@ use std::str::FromStr;
 
 use crate::agent_type::definition::Variables;
 use crate::agent_type::error::AgentTypeError;
+use crate::agent_type::runtime_config::on_host::executable::{Args, Env};
 use crate::agent_type::runtime_config::on_host::package::rendered::{Repository, Version};
 use crate::agent_type::runtime_config::templateable_value::TemplateableValue;
 use crate::agent_type::templates::Templateable;
@@ -14,6 +15,9 @@ pub mod rendered;
 pub(super) struct Package {
     /// Download defines the supported repository sources for the packages.
     pub download: Download,
+    /// Post-download hook script to execute after downloading and extracting the package.
+    /// All validations, checks, and installation steps should go here.
+    pub post_download_hook: Option<PostDownloadHook>,
 }
 
 pub type PackageID = String;
@@ -35,11 +39,37 @@ pub struct Oci {
     pub public_key_url: Option<TemplateableValue<String>>,
 }
 
+#[derive(Debug, Deserialize, Clone, PartialEq)]
+pub struct PostDownloadHook {
+    /// Path to the command/executable to run.
+    /// Can be an absolute path (e.g., "/bin/bash") or a command name to search in PATH (e.g., "bash").
+    /// Supports shell interpreters or direct binaries.
+    pub path: TemplateableValue<String>,
+
+    /// Arguments passed to the command.
+    /// - When using a shell: first arg is typically the script path, followed by script arguments
+    ///   Example: ["/path/to/install.sh", "--check-dependencies", "--verbose"]
+    /// - When using a binary directly: arguments for that binary (can be empty)
+    ///   Example: ["--flag", "value"] or []
+    #[serde(default)]
+    pub args: Args,
+
+    /// Environmental variables passed to the process.
+    #[serde(default)]
+    pub env: Env,
+}
+
 impl Templateable for Package {
     type Output = rendered::Package;
     fn template_with(self, variables: &Variables) -> Result<Self::Output, AgentTypeError> {
+        let post_download_hook = self
+            .post_download_hook
+            .map(|pd| pd.template_with(variables))
+            .transpose()?;
+
         Ok(Self::Output {
             download: self.download.template_with(variables)?,
+            post_download_hook,
         })
     }
 }
@@ -86,6 +116,17 @@ impl Templateable for Oci {
     }
 }
 
+impl Templateable for PostDownloadHook {
+    type Output = rendered::PostDownloadHook;
+    fn template_with(self, variables: &Variables) -> Result<Self::Output, AgentTypeError> {
+        let path = self.path.template_with(variables)?;
+        let args = self.args.template_with(variables)?;
+        let env = self.env.template_with(variables)?;
+
+        Ok(Self::Output { path, args, env })
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use std::str::FromStr;
@@ -140,4 +181,58 @@ mod tests {
         assert_eq!(rendered_oci.version, Version::from_str(&version).unwrap());
         assert_eq!(rendered_oci.public_key_url, public_key_url);
     }
+
+    #[test]
+    fn test_post_download_hook_template_with_variables() {
+        use std::collections::HashMap;
+
+        let mut variables = Variables::new();
+        variables.insert(
+            "nr-var:version".to_string(),
+            Variable::new_final_string_variable("1.0.0".to_string()),
+        );
+        variables.insert(
+            "nr-var:script-path".to_string(),
+            Variable::new_final_string_variable("/opt/install.sh".to_string()),
+        );
+        variables.insert(
+            "nr-var:env-value".to_string(),
+            Variable::new_final_string_variable("test-value".to_string()),
+        );
+
+        let mut env_map = HashMap::new();
+        env_map.insert(
+            "AGENT_VERSION".to_string(),
+            TemplateableValue::from_template("${nr-var:version}".to_string()),
+        );
+        env_map.insert(
+            "CUSTOM_VAR".to_string(),
+            TemplateableValue::from_template("${nr-var:env-value}".to_string()),
+        );
+
+        let post_download_hook = PostDownloadHook {
+            path: TemplateableValue::from_template("/bin/bash".to_string()),
+            args: Args(vec![
+                TemplateableValue::from_template("${nr-var:script-path}".to_string()),
+                TemplateableValue::from_template("--version=${nr-var:version}".to_string()),
+            ]),
+            env: Env(env_map),
+        };
+
+        let rendered = post_download_hook.template_with(&variables).unwrap();
+
+        assert_eq!(rendered.path, "/bin/bash");
+        assert_eq!(rendered.args.0.len(), 2);
+        assert_eq!(rendered.args.0[0], "/opt/install.sh");
+        assert_eq!(rendered.args.0[1], "--version=1.0.0");
+        assert_eq!(rendered.env.0.len(), 2);
+        assert_eq!(
+            rendered.env.0.get("AGENT_VERSION"),
+            Some(&"1.0.0".to_string())
+        );
+        assert_eq!(
+            rendered.env.0.get("CUSTOM_VAR"),
+            Some(&"test-value".to_string())
+        );
+    }
 }

agent-control/src/agent_type/runtime_config/on_host/package/rendered.rs

@@ -1,10 +1,10 @@
-use std::{fmt::Display, str::FromStr};
-
 use oci_client::Reference;
 use serde::{Deserialize, Serialize};
+use std::{fmt::Display, str::FromStr};
 use url::Url;
 
 use crate::agent_control::config::Registry;
+use crate::agent_type::runtime_config::on_host::executable::rendered::{Args, Env};
 
 const REPOSITORY_TOTAL_LENGTH_MAX: usize = 255;
 const TAG_TOTAL_LENGTH_MAX: usize = 128;
@@ -13,6 +13,8 @@ const TAG_TOTAL_LENGTH_MAX: usize = 128;
 pub struct Package {
     /// Download defines the supported repository sources for the packages.
     pub download: Download,
+    /// Post-download hook script to execute after downloading and extracting the package.
+    pub post_download_hook: Option<PostDownloadHook>,
 }
 
 #[derive(Debug, Clone, PartialEq)]
@@ -28,6 +30,16 @@ pub struct Oci {
     pub public_key_url: Option<Url>,
 }
 
+#[derive(Debug, Clone, PartialEq)]
+pub struct PostDownloadHook {
+    /// Absolute path to the command/executable (e.g., "/bin/bash", "/usr/bin/python3")
+    pub path: String,
+    /// Arguments passed to the executable on [`path`].
+    pub args: Args,
+    /// Environmental variables
+    pub env: Env,
+}
+
 const DEFAULT_TAG: &str = "latest";
 
 impl Oci {

agent-control/src/package.rs

@@ -1,2 +1,3 @@
 pub mod manager;
 pub mod oci;
+pub mod post_download_hook_executor;

agent-control/src/package/manager.rs

@@ -1,6 +1,6 @@
 //! This module manages package operations such as installation, removal, and updates.
 use crate::agent_control::agent_id::AgentID;
-use crate::agent_type::runtime_config::on_host::package::rendered::Oci;
+use crate::agent_type::runtime_config::on_host::package::rendered::{Oci, PostDownloadHook};
 use crate::package::oci::package_manager::OCIPackageManagerError;
 use std::path::PathBuf;
 
@@ -9,6 +9,7 @@ use std::path::PathBuf;
 pub struct PackageData {
     pub id: String, // same type as the packages map on an agent type definition
     pub oci: Oci,
+    pub post_download_hook: Option<PostDownloadHook>,
 }
 
 /// Information about an installed package

agent-control/src/package/oci/downloader.rs

@@ -168,6 +168,7 @@ pub mod tests {
                 version: Version::from_str(VERSION).unwrap(),
                 public_key_url,
             },
+            post_download_hook: None,
         }
     }