PR #24914: feat: One gateway for multiple agent profiles.

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

Description (problem / solution / changelog)

What does this PR do?

Lets a single gateway process serve multiple Hermes profiles as switchable agents — instead of needing one gateway per profile bound to a separate platform credential.

User-facing surface

Isolation guarantees

• Memory / skills / SOUL.md: hard-isolated per profile (existing ~/.hermes/profiles/<name>/ layout)
• Session / transcript: each (chat, agent) pair has its own session_id — switching back to a previously-used agent resumes its own conversation, no leakage from other agents
• Gateway runtime state (sessions DB, host platform tokens): stays in the host profile

Mechanism

• HERMES_HOME becomes a ContextVar; get_hermes_home() consults it first → per-turn agent swap with no env-var rebind
• _run_agent wraps the executor in agent_home_scope(<agent.home>) so AIAgent construction + run-conversation see the right paths
• build_session_key takes agent_name → (chat, agent) pairs get distinct session_keys → distinct transcripts; chat bindings persist to sessions/chat_bindings.json
• default agent keeps the legacy agent:main:... prefix → zero migration for existing state.db / sessions.json

Details see #24913

Related Issue

<!-- Link the issue this PR addresses. If no issue exists, consider creating one first. -->

Fixes #24913

Type of Change

<!-- Check the one that applies. -->

• 🐛 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

<!-- List the specific changes. Include file paths for code changes. -->

How to Test

<!-- Steps to verify this change works. For bugs: reproduction steps + proof that the fix works. -->

1. Added comprehensive unit tests
2. Test locally.

Checklist

<!-- Complete these before requesting review. -->

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

<!-- Check all that apply. It's OK to check "N/A" if a category doesn't apply to your change. -->

• 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

For New Skills

<!-- Only fill this out if you're adding a skill. Delete this section otherwise. -->

• This skill is broadly useful to most users (if bundled) — see Contributing Guide
• SKILL.md follows the standard format (frontmatter, trigger conditions, steps, pitfalls)
• No external dependencies that aren't already available (prefer stdlib, curl, existing Hermes tools)
• I've tested the skill end-to-end: hermes --toolsets skills -q "Use the X skill to do Y"

Screenshots / Logs

<!-- If applicable, add screenshots or log output showing the fix/feature in action. -->

Changed files

• AGENTS.md (modified, +91/-0)
• cli.py (modified, +64/-6)
• gateway/__init__.py (modified, +4/-0)
• gateway/agent_context.py (added, +78/-0)
• gateway/agent_mention.py (added, +94/-0)
• gateway/agent_registry.py (added, +274/-0)
• gateway/agent_response.py (added, +105/-0)
• gateway/run.py (modified, +248/-15)
• gateway/session.py (modified, +214/-9)
• hermes_cli/commands.py (modified, +5/-1)
• hermes_constants.py (modified, +25/-1)
• tests/e2e/test_multi_agent.py (added, +251/-0)
• tests/gateway/test_agent_context.py (added, +167/-0)
• tests/gateway/test_agent_mention.py (added, +124/-0)
• tests/gateway/test_agent_registry.py (added, +220/-0)
• tests/gateway/test_agent_response.py (added, +110/-0)
• tests/gateway/test_multi_agent_isolation.py (added, +200/-0)
• tests/gateway/test_profile_command.py (added, +177/-0)
• tests/gateway/test_resolve_turn_agent.py (added, +137/-0)
• tests/gateway/test_session_active_agent.py (added, +169/-0)