PR #17518: fix(agent): cascade nested fallback_model chains

• Repository: NousResearch/hermes-agent
• Author: LeonSGP43
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/17518

Description (problem / solution / changelog)

Summary

Fixes #17485.

Legacy configs can express multi-level provider failover by nesting fallback_model blocks. Hermes only kept the first dict in _fallback_chain, so after fallback 1 failed with a non-retryable/auth error, the retry loop had no second provider to activate and aborted despite the nested fallback config.

This normalizes fallback config into an ordered chain before agent startup:

• keeps the canonical list-form fallback_providers / list fallback_model behavior
• preserves single-dict fallback_model behavior
• flattens nested legacy fallback_model entries so fallback 1 can cascade to fallback 2

Verification

• scripts/run_tests.sh tests/run_agent/test_provider_fallback.py (22 passed)
• git diff --check

Scope

This only changes fallback-chain normalization and focused fallback tests. It does not alter provider-specific auth refresh, retry classification, or the canonical fallback command/config storage format.

Changed files

• run_agent.py (modified, +34/-9)
• tests/run_agent/test_provider_fallback.py (modified, +62/-0)

PR #17535: fix(run_agent): normalize nested fallback chains to enable cascading provider failover

• Repository: NousResearch/hermes-agent
• Author: afurm
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/17535

Description (problem / solution / changelog)

What does this PR do?

This PR fixes provider fallback handling in run_agent.py by normalizing legacy nested fallback_model blocks into a single ordered runtime chain. Previously, nested fallback definitions could be skipped during failover, so fallback resolution did not consistently cascade past the first fallback provider. This change ensures fallback resolution is deterministic and traverses the full chain, including the nested case reported in #17485.

Related Issue

Fixes #17485

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

• run_agent.py: Added fallback-chain normalization logic to flatten legacy nested fallback_model payloads into the runtime fallback chain order, enabling proper cascade behavior.
• tests/run_agent/test_provider_fallback.py: Added regression tests for:
  • nested fallback chain normalization
  • cascading fallback when an earlier fallback target raises a 401-like error
• tests/run_agent/test_fallback_model.py: Kept/verified coverage aligned with the updated normalization behavior and edge cases.

How to Test

1. Run fallback provider tests:
   • scripts/run_tests.sh tests/run_agent/test_provider_fallback.py -q
   • scripts/run_tests.sh tests/run_agent/test_fallback_model.py -q
2. Confirm both suites pass:
   • test_provider_fallback.py: 21 passed
   • test_fallback_model.py: 28 passed
3. Add a provider configuration with a nested fallback chain and simulate a first fallback returning 401-like error; verify the agent continues cascading through the normalized fallback order and does not stop prematurely.

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 fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: <!-- e.g. Ubuntu 24.04, macOS 15.2, Windows 11 -->

Documentation & Housekeeping

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

Screenshots / Logs

• scripts/run_tests.sh tests/run_agent/test_provider_fallback.py -q → 21 passed
• scripts/run_tests.sh tests/run_agent/test_fallback_model.py -q → 28 passed

Changed files

• run_agent.py (modified, +35/-11)
• tests/run_agent/test_provider_fallback.py (modified, +35/-0)