fix: .env Namespaced Character Secrets

[genecyber]

Relates to:

N/A

Risks

Medium - This PR adds a new feature for character-specific environment variable namespacing.

Risks include:

• Changes to environment variable handling
• Changes to character settings loading
• Potential impact on existing character configurations

Background

I wanted to be able to check in character files without having to sanitize them first

What does this PR do?

Feature Implementation

Adds support for character-specific namespaced environment variables:

1. New environment variable pattern: CHARACTER.YOUR_CHARACTER_NAME.SETTING_NAME
2. Automatic handling of spaces in character names (converted to underscores)
3. Enhanced settings hierarchy:
   • Character-specific namespaced env variables (highest priority)
   • Character settings from JSON
   • Global environment variables
   • Default values
4. Maintains backward compatibility with existing settings system

Key changes:

• Modified settings loader in packages/core/src/settings.ts
• Updated character loading in packages/agent/src/index.ts
• Added automatic conversion of character name spaces to underscores

Documentation Updates

Updated documentation to reflect the new feature:

1. Added namespaced settings pattern to secrets management guide
2. Updated configuration guide with new examples
3. Updated agent package documentation with hierarchy explanation
4. Added clear examples for both .env and character.json methods

What kind of change is this?

Features (non-breaking change which adds functionality)

Documentation changes needed?

Yes - Documentation has been updated to reflect the new feature:

• Added namespaced settings pattern
• Updated configuration examples
• Updated settings hierarchy explanation
• Added character name handling instructions

Testing

Where should a reviewer start?

Feature Testing

1. Review code changes:

   • packages/core/src/settings.ts
   • packages/agent/src/index.ts

2. Test functionality:

   # Test with simple name
   CHARACTER.TESTBOT.OPENAI_API_KEY=sk-test
   
   # Test with spaces in name
   CHARACTER.MY_TEST_BOT.ANTHROPIC_API_KEY=sk-other

Documentation Testing

Review updated docs:

• docs/docs/guides/secrets-management.md
• docs/docs/guides/configuration.md
• docs/docs/packages/agent.md

Detailed testing steps

1. Feature Testing:

   • Create character with spaces in name
   • Add namespaced variables to .env
   • Verify correct loading into character settings
   • Test precedence over character.json settings
   • Verify backward compatibility
   • Test global fallback behavior

2. Documentation Verification:

   • Verify pattern examples are correct
   • Verify hierarchy explanation is clear
   • Verify character name handling is explained
   • Test example configurations

Screenshots

N/A - Feature implementation and documentation changes

[monilpat]

Thanks for getting this out! Great work! Given it is of medium risk, can we add a quick unit test to confirm that the cascading logic (in terms of where to read the settings) works as expected. If you don't want to include this in this PR no worries create a ticket and TODO comment. But please confirm on your machine that the precedence is honored re:

1. Character-specific namespaced environment variables (highest priority)
2. Character-specific secrets
3. Environment variables
4. Default values (lowest priority)

Thanks so much!

[genecyber]

good idea, I'll add tests. Is the suite in pretty good condition? I didn't try yet.