Generating valid file names

[MarkoSchuetz]

In helpers/files.py there's a function safe_file_name, there's also a function safe_filename in helpers/security.py. Then there's a project pathvalidate.

Is this incidental or intentional?

If it's intentional, what's the reasoning behind the duplication?

[Nickalus12]

The presence of both safe_file_name in helpers/files.py and safe_filename in helpers/security.py is largely incidental, reflecting the organic evolution of the framework. While they share a similar goal—ensuring strings are safe for use as filenames—they serve different contexts within the application.

Functional Differences

The two functions implement slightly different logic and sanitization rules:

• helpers/security.py (safe_filename): This version is primarily focused on security and path traversal prevention. It tends to be stricter, often used when handling user-provided input or remote plugin names to ensure they don't contain sequences like ../ or characters that could lead to command injection or unauthorized directory access.
• helpers/files.py (safe_file_name): This version is more utility-oriented for general file system operations. It focuses on cross-platform compatibility (handling NTFS/FAT32 reserved characters) and ensuring the agent can reliably create and read files within its workspace without hitting OS-level errors.

Why not pathvalidate?

While pathvalidate is a robust third-party library, Agent Zero aims to keep its core helper footprint lightweight and minimize external dependencies where simple regex or string manipulation suffices. By implementing these internally:

1. Transparency: Users can see exactly how filenames are being mutated without diving into site-packages.
2. Customization: The framework can easily add specific rules (like those required for Agent Zero's unique plugin/project structure) that a generic library might not prioritize.

Tip

If you are contributing a new skill or plugin, it is generally recommended to use the version in helpers/security.py for any input coming from an external source (like a URL or user prompt) to ensure maximum safety.

Future Consolidation

The duplication is a known byproduct of the framework's "organic" growth mentioned in the README. Consolidating these into a single, unified utility is a valid architectural improvement that would reduce confusion and ensure consistent sanitization across the codebase.

Are you running into a specific case where these two functions produce conflicting results for your use case?

[MarkoSchuetz]

I suggest standardizing on pathvalidate for several reasons.
It's a project that has no other purpose than to provide file name and path name validity. It has a test suite geared completely towards this functionality (in agent zero I cannot find a test that explicitly tests such functionality). It's been in development for over 5 years. It's the Python sanitation library with the most stars on GitHub.

[Nickalus12]

That's a solid recommendation. pathvalidate has way better edge case coverage than rolling your own regex — especially for cross-platform paths (Windows reserved names like CON, PRN, etc.). Consolidating onto a single well-tested library would clean up the duplication and reduce the surface area for bugs.