hermes - 💡(How to fix) Fix Crash on Python <3.10: TypeError with X | None type hints

Bug Description

Hermes Agent crashes immediately on Python 3.9 with TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'

Steps to Reproduce

1. Use Python 3.9 (or < 3.10)
2. Run hermes --version or any hermes command
3. Observe crash

Error Output

Traceback (most recent call last):
  File "/path/to/hermes-agent/hermes", line 10, in <module>
    from hermes_cli.main import main
  File "/path/to/hermes-agent/hermes_cli/main.py", line 6452, in <module>
    env: dict[str, str] | None = None,
TypeError: unsupported operand type(s) for |: 'types.GenericAlias' and 'NoneType'

Root Cause

Multiple files use Python 3.10+ type hint syntax (X | None, dict[str, str] | None) without:

1. Adding from __future__ import annotations to make it a string annotation (forward-compatible)
2. Or checking Python version >= 3.10 in the launcher

Affected files include:

• hermes_constants.py
• utils.py
• hermes_cli/main.py
• Many plugin/model provider files (shown in "Failed to load bundled provider plugin" warnings)

Suggested Fix

1. Add from __future__ import annotations to ALL Python files that use | type syntax
2. OR add Python version check in hermes launcher script:

import sys
if sys.version_info < (3, 10):
    raise RuntimeError("Hermes Agent requires Python 3.10 or higher")

Environment

• OS: macOS (LibreSSL 2.8.3)
• Python: 3.9.x (system) or 3.11.x (venv)
• Hermes Agent: v0.13.0 (2026.5.7)

Workaround

Use Python 3.11+ via venv, or fix shebang to point to correct Python binary.