PR #17994: feat(cli): add /free-models command to list free OpenRouter models

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

Description (problem / solution / changelog)

What

Adds /free-models slash command that lists every OpenRouter model with free pricing and tool-calling support, fetched live from openrouter.ai/api/v1/models.

Resolves #17923.

Why

Free models are a key entry point for users evaluating Hermes Agent, but the existing /model picker only surfaces models that are explicitly in the curated OPENROUTER_MODELS list. Free :free variants like nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free exist on OpenRouter but aren't discoverable through the CLI today.

How

1. New helper fetch_openrouter_free_models() in hermes_cli/models.py that hits the live OpenRouter /v1/models endpoint, filters to models where pricing.prompt and pricing.completion are both zero AND supported_parameters advertises tools, then returns [(id, "free"), ...]. Reuses the existing _openrouter_model_is_free and _openrouter_model_supports_tools helpers so policy stays consistent with the curated picker.

2. Network/parse failures fall back to the :free entries already in OPENROUTER_MODELS so the command still works offline.

3. New /free-models CommandDef in hermes_cli/commands.py and handler _handle_free_models_command in cli.py that prints the list with a hint on how to switch.

4. Six tests covering: free+tool filtering, tool-support filtering, permissive handling of missing supported_parameters, network-failure fallback, malformed-payload fallback, and de-duplication.

Why a separate command and not /model --free

The issue suggested either a --free flag on /model or a separate /free-models command. I went with the separate command because the /model picker pulls from a hardcoded curated list across multiple providers (OPENROUTER_MODELS, _PROVIDER_MODELS), and threading a free-only mode through parse_model_flags, switch_model, and list_authenticated_providers would be a much larger change that touches the CLI, gateway, and TUI gateway. A standalone command keeps the diff small and surface area predictable. Happy to reshape if you'd prefer the flag approach — just let me know.

Test plan

• python3 -m py_compile on all modified files
• Manual runtime test of fetch_openrouter_free_models with mocked OpenRouter responses (filter, fallback, dedup paths)
• resolve_command("free-models") returns the registered CommandDef
• CI runs the new test class on push

Followup ideas

• Adding context-length info next to each model id (the live payload exposes context_length)
• Sorting by context length / popularity for nicer output
• Wiring the same source into the /model picker behind a --free flag (separate PR if the maintainer wants this)

Changed files

• cli.py (modified, +26/-0)
• hermes_cli/commands.py (modified, +2/-0)
• hermes_cli/models.py (modified, +53/-0)
• tests/hermes_cli/test_models.py (modified, +125/-0)