feat(gateway): make agent cache idle TTL configurable

[HwangJohn]

What does this PR do?

Adds agent.cache_idle_ttl_seconds so gateway users can tune how long idle in-memory agents remain cached between messages.

The default remains 3600 seconds, preserving the existing one-hour eviction behavior. Setting the value to 0 disables idle eviction for long-lived messaging threads, while the existing hard cache size cap still bounds growth.

This is related to, but not a duplicate of, #31856. That PR changes when the idle sweep may evict agents relative to session expiry. This PR adds an explicit user-facing TTL setting for deployments that need a different idle retention window.

Fixes #47730

Related Issue

Fixes #47730

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• Added agent.cache_idle_ttl_seconds to DEFAULT_CONFIG.
• Resolved the gateway agent-cache idle TTL from config at GatewayRunner startup.
• Treated 0/false as idle eviction disabled while falling back to the historical default for invalid or negative values.
• Updated cli-config.yaml.example and website/docs/user-guide/configuration.md.
• Added agent-cache tests for disabled TTL, configured TTL, and invalid config fallback.

How to Test

1. Set agent.cache_idle_ttl_seconds: 0 and start the gateway. Idle cached agents are no longer evicted by the idle TTL sweep.
2. Set a positive value such as agent.cache_idle_ttl_seconds: 7200 and restart the gateway. Idle eviction uses that configured TTL.
3. Leave the key unset. The gateway keeps the existing 3600-second behavior.

Validation run:

• DGX Spark Linux: scripts/run_tests.sh tests/gateway/test_config_env_bridge_authority.py tests/gateway/test_agent_cache.py -> 77 passed.
• DGX Spark Linux: ~/.hermes/hermes-agent/venv/bin/python -m ruff check gateway/run.py hermes_cli/config.py tests/gateway/test_agent_cache.py -> passed.
• DGX Spark Linux: git diff --check origin/main...fix/47730-agent-cache-idle-ttl -> passed after rebase.
• Windows: .\\.venv\\Scripts\\python -m pytest tests\\gateway\\test_agent_cache.py -q -> 71 passed.
• Windows: .\\.venv\\Scripts\\python -m ruff check gateway\\run.py hermes_cli\\config.py tests\\gateway\\test_agent_cache.py -> passed.

Broader gateway sweep:

• scripts/run_tests.sh tests/gateway reached 6905 passed, 6 failed in tests/gateway/test_matrix_voice.py.
• The same Matrix voice failures reproduce on clean origin/main, so they are pre-existing and unrelated to this branch.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this feature
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes
• I've tested on my platform: Windows local and DGX Spark Linux

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings)
• I've updated cli-config.yaml.example if I added/changed config keys
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide
• I've updated tool descriptions/schemas if I changed tool behavior — N/A

Screenshots / Logs

Not applicable. This is a gateway configuration behavior change covered by tests.

[teknium1]

Thanks for isolating a real remaining configuration gap. Upstream main still hard-codes the one-hour idle TTL at gateway/run.py:68 and uses it in the sweep at gateway/run.py:16756; the maintainer resolution on linked #33563 also identifies this PR as the open config-exposure follow-up.

Problems

• The new parser's ttl < 0 guard does not reject non-finite floats. float("nan") succeeds and passes that comparison; current sweep checks (idle_ttl_secs <= 0 and age > idle_ttl_secs) are both false for NaN, silently disabling eviction rather than taking the documented fallback. See added gateway/run.py:1512 and current gateway/run.py:16756.
• The branch predates the session-finalizability safeguard now in gateway/run.py:16756-16795. The salvage must preserve its behavior for finite, unexpired sessions; the proposed tests do not cover that current path.

Suggested changes

• Reject non-finite TTLs with math.isfinite() and add NaN/Infinity fallback tests.
• Carry the setting onto the current sweep while retaining the session-store guard; test mode=none configured TTLs and finite-session preservation.

Automated hermes-sweeper review.

[teknium1]

float("nan") succeeds and nan < 0 is false. The sweep's later <= 0 and age-comparison checks also both evaluate false for NaN, so this accidentally disables eviction instead of falling back to 3600. Reject non-finite values (for example with math.isfinite(ttl)) and add a regression test.