hermes - 💡(How to fix) Fix feat: generalize nous_rate_guard to a universal provider rate limit guard [1 participants]

Summary

agent/nous_rate_guard.py currently provides a cross-session rate limit guard exclusively for the Nous Portal provider. This FR proposes generalizing it into a universal provider rate limit guard that benefits all providers (OpenAI-compatible, Z.ai/DashScope, etc.) with the same preventive pattern.

Current State

nous_rate_guard.py works well for Nous:

• Pre-request check: Before each API call, checks shared state file. If rate-limited, skips the call entirely (prevents RPH amplification from retries).
• Post-429 recording: Records rate limit state with reset time parsed from response headers.
• Post-success clearing: Clears rate limit state after a successful request.
• Atomic file writes: Uses tempfile + os.replace for safe writes.
• Shared state: File at ~/.hermes/rate_limits/nous.json, readable by all sessions (CLI, gateway, cron).

However, this logic only triggers when self.provider == "nous" (hardcoded at 3 call sites in run_agent.py).

Proposed Changes

1. Rename and generalize the module

agent/nous_rate_guard.py → agent/provider_rate_guard.py

Replace Nous-specific functions with provider-agnostic ones:

The provider parameter maps to the same {provider}.json file convention. No model-level granularity needed — rate limits are API-key/account level, so one provider being rate-limited means all its models are unavailable.

2. Replace hardcoded provider == "nous" checks

In run_agent.py, replace 3 hardcoded Nous guards with generic provider calls:

# Before (3 locations):
if self.provider == "nous":
    from agent.nous_rate_guard import nous_rate_limit_remaining
    ...

# After:
from agent.provider_rate_guard import provider_rate_limit_remaining
_remaining = provider_rate_limit_remaining(self.provider)
if _remaining is not None and _remaining > 0:
    ...

Same for record_provider_rate_limit and clear_provider_rate_limit.

3. Keep Nous as default behavior, add config opt-in for other providers

By default, the guard activates for all providers (opt-out via config if needed). Alternatively, guard only providers that have been observed rate-limited (lazy activation — no guard file = not rate-limited).

4. Chinese date format parsing

For Z.ai/DashScope and similar Chinese API providers, rate limit reset times may come in Chinese format (e.g. 您的限额将在 2026-04-19 06:17:24 重置). The _extract_api_error_context() method in run_agent.py should parse these into a numeric reset_at timestamp so the guard can use them. This is currently missing.

Benefits

• All providers benefit: Z.ai, DashScope, OpenAI-compatible, etc. — no more repeated 429 → fallback cycles for each turn.
• Preventive pattern: Same efficiency gain as Nous — skip the API call entirely when rate-limited, avoiding retry amplification.
• No extra dependencies: Reuses existing file-based shared state mechanism.
• Backward compatible: Nous behavior unchanged, other providers gain new capability.

References

• Previous Nous-specific implementation: agent/nous_rate_guard.py (182 lines)