hermes - 💡(How to fix) Fix [BUG] web-tavily plugin fails to register: PluginContext missing register_web_search_provider

Description

The web-tavily plugin fails to load during gateway startup with the error:

Failed to load plugin 'web-tavily': 'PluginContext' object has no attribute 'register_web_search_provider'

This causes the web_search tool to return:

"No web search provider configured. Run `hermes tools` to set one up."

Environment

• Hermes Agent version: Latest (commit around cae753735)
• Python: 3.12.3
• Platform: Linux (WSL2 / Ubuntu)
• Config: web.search_backend: tavily, web.extract_backend: tavily
• TAVILY_API_KEY: Configured correctly in ~/.hermes/.env

Evidence

1. Error log (from ~/.hermes/logs/errors.log)

2026-05-20 05:16:09,470 WARNING hermes_cli.plugins: Failed to load plugin 'web-tavily': 'PluginContext' object has no attribute 'register_web_search_provider'

Same error occurs for other web plugins: web-exa, web-firecrawl, web-parallel, web-searxng, web-brave-free, web-ddgs.

2. Method exists in source code

# ~/.hermes/hermes-agent/hermes_cli/plugins.py:585
def register_web_search_provider(self, provider) -> None:
    """Register a web search/extract backend."""
    ...

3. Manual test confirms method works

$ python3 -c "
import sys; sys.path.insert(0, '/home/yu/.hermes/hermes-agent')
from hermes_cli.plugins import PluginContext
print(hasattr(PluginContext, 'register_web_search_provider'))
# Output: True
"

4. Clean plugin discovery works

$ python3 -c "
import sys; sys.path.insert(0, '/home/yu/.hermes/hermes-agent')
from hermes_cli.plugins import discover_plugins, get_plugin_manager
from agent.web_search_registry import list_providers

pm = get_plugin_manager()
pm._plugins.clear()
pm._discovered = False

discover_plugins(force=True)
providers = list_providers()
for p in providers:
    print(f'  - {p.name}')
# Output:
#   - tavily
#   - xai
"

5. But fails during gateway startup

The gateway calls discover_plugins() at startup (line ~3830 in gateway/run.py), but the plugin registration fails silently.

Root Cause Analysis

The issue appears to be a race condition or import order problem in the plugin system:

1. PluginContext is defined in hermes_cli/plugins.py with register_web_search_provider method
2. The web-tavily plugin (plugins/web/tavily/__init__.py) calls ctx.register_web_search_provider(TavilyWebSearchProvider())
3. During gateway startup, the plugin fails with 'PluginContext' object has no attribute 'register_web_search_provider'
4. But in a fresh Python process, the method exists and works correctly

This suggests that during gateway startup:

• The PluginContext class may be partially initialized
• Or there is a circular import causing the class definition to be incomplete
• Or the PluginManager singleton is in an inconsistent state

Steps to Reproduce

1. Configure web.search_backend: tavily in ~/.hermes/config.yaml
2. Ensure TAVILY_API_KEY is set in ~/.hermes/.env
3. Run hermes gateway run --replace
4. Observe error in ~/.hermes/logs/errors.log
5. Call web_search tool → returns "No web search provider configured"

Expected Behavior

The web-tavily plugin should register successfully, and web_search should use Tavily as the backend.

Additional Notes

• TAVILY_API_KEY is correctly loaded via load_hermes_dotenv()
• Direct API calls to Tavily work fine
• The issue is specifically with the plugin registration mechanism
• Other web plugins (exa, firecrawl, parallel, searxng, brave-free, ddgs) show the same error