feat(caching): HERMES_CACHE_TTL env var to enable 1h prompt cache

[Nazariy995]

What does this PR do?

Enables the 1-hour Anthropic prompt-cache tier via a new HERMES_CACHE_TTL env var. The "1h" TTL path has been supported inside apply_anthropic_cache_control() since it landed, but there was no user-facing way to reach it — self._cache_ttl was hardcoded to "5m" at run_agent.py:1001.

Why this matters: On Anthropic, a 1h cache-write costs 2x the base input rate (vs 1.25x for 5m), but the cached prefix survives 12x longer. It's a clear win for workflows where the same prefix gets reused with gaps > 5 min — coding sessions with meeting breaks, sparse cron-driven agents, long-form research. Before this PR, enabling the 1h tier required forking hermes-agent or monkey-patching AIAgent._cache_ttl at runtime.

Design: Read the env var directly at AIAgent.__init__ time rather than threading a kwarg through the gateway → runner → AIAgent path. This keeps the config surface stable across CLI, gateway, batch_runner, cron, and any future entry point without touching ~30 files. Invalid values ("30m", "forever", typos) fall back silently to "5m" so a mistake in .env never crashes a conversation mid-turn.

Related Issue

Fixes #

Type of Change

• ✨ New feature (non-breaking change that adds functionality)

Changes Made

• run_agent.py:1001 — read HERMES_CACHE_TTL from env, validate against {"5m", "1h"}, fall back to "5m" on any other value
• tests/agent/test_prompt_caching.py — new TestCacheTTLEnvOverride class with 5 cases

How to Test

1. Default behavior (unchanged):

   unset HERMES_CACHE_TTL
   pytest tests/agent/test_prompt_caching.py -q

2. Enable 1h tier:

   echo "HERMES_CACHE_TTL=1h" >> ~/.hermes/.env
   # Restart Hermes CLI/gateway; chat a couple of turns.
   # Inspect the outgoing Anthropic payload and confirm
   # cache_control: { type: "ephemeral", ttl: "1h" } on the system prompt.

3. Typo resilience:

   HERMES_CACHE_TTL=30m pytest tests/agent/test_prompt_caching.py::TestCacheTTLEnvOverride::test_env_invalid_falls_back_to_5m -q

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (feat(caching): ...)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this feature (no unrelated commits)
• I've run pytest tests/agent/test_prompt_caching.py -q — 19/19 pass
• I've added tests for my changes (5 new cases)
• I've tested on my platform: macOS 15 (darwin 25.0)

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — N/A for this PR; website/docs/developer-guide/context-compression-and-caching.md already documents cache_ttl: "5m" or "1h" as valid values. Happy to add a paragraph pointing users at the env var if maintainers want — let me know.
• I've updated cli-config.yaml.example if I added/changed config keys — N/A (env var only, no YAML key)
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — N/A
• I've considered cross-platform impact (Windows, macOS) — os.getenv() is stdlib, works identically everywhere
• I've updated tool descriptions/schemas if I changed tool behavior — N/A

Screenshots / Logs

Before (hardcoded "5m"):

"cache_control": { "type": "ephemeral" }

After, with HERMES_CACHE_TTL=1h:

"cache_control": { "type": "ephemeral", "ttl": "1h" }

Test run:

$ pytest tests/agent/test_prompt_caching.py -q
...................                                                      [100%]
19 passed in 0.72s

[alt-glitch]

Likely duplicate of #3082 — same feature (configurable Anthropic prompt cache TTL). Also overlaps with #12659 which adds config knob. This PR uses env var approach vs config.yaml.

[teknium1]

Thanks for the PR @Nazariy995 — same TTL-configurability goal was met via salvage #15065 (of parallel #12659).

Closed because Hermes's policy is .env for secrets only; behavioral settings like cache TTL belong in config.yaml. That's why we went with the config-based approach. Your env-var-as-escape-hatch thinking is sound in general, we just reserve that pattern for credentials.

Appreciate the detailed cost analysis in the body — exactly the kind of real-workload motivation that moves a feature forward. Please keep contributing.

[Nazariy995]

@teknium1 thank you for that appreciate it! i am loving this project!