feat(stt): add register_transcription_provider() plugin hook + stt.providers command-provider registry

Salvages PR #30493 (@kshitijk4poor) onto current main and adds the symmetric STT command-provider registry that #31745 just established for TTS. Both new STT extension surfaces ship together so the precedence rules are symmetric across the two tools from day one.

What this PR makes true that wasn't before

New STT engines can plug into Hermes without modifying tools/transcription_tools.py. Two coexisting surfaces, picked per use case:

1. stt.providers.<name>: type: command — any shell-driven ASR engine (Doubao ASR, NVIDIA Parakeet, whisper.cpp builds, SenseVoice CLI, curl … | jq -r .text pipelines). Zero Python.
2. ctx.register_transcription_provider() — Python-SDK engines (OpenRouter, SenseAudio, Gemini-STT, Deepgram) that can't be expressed as a single shell command.

The 6 built-in providers (local, local_command, groq, openai, mistral, xai) keep their native handlers and always win on name collision. HERMES_LOCAL_STT_COMMAND is preserved untouched via the built-in local_command path.

Resolution order (mirrors TTS exactly after #31745)

1. stt.provider is a built-in name → built-in dispatch. Always wins.
2. stt.provider matches stt.providers.<name> with command: set → command-provider runner.
3. stt.provider matches a plugin-registered TranscriptionProvider → plugin dispatch.
4. No match → "No STT provider available" error.

Same precedence as TTS: config more local than plugin install, built-ins always win.

Files

New

• agent/transcription_provider.py — TranscriptionProvider(ABC) mirroring tts_provider.py shape (from feat(stt): add register_transcription_provider() plugin hook #30493).
• agent/transcription_registry.py — registry mirroring tts_registry.py shape, _BUILTIN_NAMES reject-shadowing invariant (from feat(stt): add register_transcription_provider() plugin hook #30493).

Modified

• hermes_cli/plugins.py — register_transcription_provider() on PluginContext. Docstring updated to spell out both invariants (built-ins-always-win + command-wins-over-plugin).
• tools/transcription_tools.py — BUILTIN_STT_PROVIDERS frozenset + _dispatch_to_plugin_provider() (from feat(stt): add register_transcription_provider() plugin hook #30493) plus _resolve_command_stt_provider_config() / _transcribe_command_stt() / local helpers for shell-quote-aware template rendering and process-tree termination on timeout (new in this PR). Wire-in is one insertion point in transcribe_audio() — command runs after built-in elif, before plugin dispatch. Plugin dispatcher additionally short-circuits when a same-name command config exists (defense in depth).
• website/docs/user-guide/features/tts.md — new "STT custom command providers" section + "When to pick which (STT)" decision table + updated resolution order (4 layers instead of 3).
• website/docs/user-guide/features/plugins.md — STT row updated to describe both surfaces with anchors to each docs section.

Tests

$ bash scripts/run_tests.sh tests/tools/test_transcription* \
                            tests/agent/test_transcription_registry.py \
                            tests/hermes_cli/test_plugins_transcription_registration.py \
                            tests/tools/test_tts_command_providers.py \
                            tests/tools/test_tts_plugin_dispatch.py
=== Summary: 11 files, 376 tests passed, 0 failed ===

$ python tests/plugins/transcription/check_parity_vs_main.py
  [OK]   stt-disabled                          [OK]   explicit-mistral-quarantine
  [OK]   explicit-groq                         [OK]   unknown-no-plugin
  [OK]   explicit-openai                       [DIFF] plugin-installed: → plugin (expected)
  [OK]   explicit-local                        [DIFF] plugin-installed-unavailable: → plugin_unavailable (expected)
  [OK]   explicit-xai                          [OK]   explicit-openai-with-plugin-registered
  [DIFF] command-provider-installed: → command_provider (expected)
  [DIFF] command-vs-plugin-same-name: → command_provider (expected — command wins over same-name plugin)
  [OK]   explicit-openai-with-command-shadow (built-in still wins)
INTENTIONAL DIFFS (4): expected new behavior from this PR.
PARITY OK across 13 scenarios.

$ bash scripts/run_tests.sh tests/tools/
=== Summary: 227 files, 5576 tests passed, 0 failed ===

$ bash scripts/run_tests.sh tests/agent/ tests/hermes_cli/
=== Summary: 367 files, 8623 tests passed, 0 failed ===

14,199 tests pass across the affected surfaces — zero regressions.

E2E live verification

Real config.yaml + real .wav + isolated HERMES_HOME + real transcribe_audio() (no mocks):

command:                    → dispatched to stt.providers.my-fake-cli (transcript: E2E_CMD_TRANSCRIPT)
plugin:                     → dispatched to registered TranscriptionProvider (transcript: E2E_PLUGIN_TRANSCRIPT)
command-wins-over-plugin:   → command provider beat the same-name plugin
builtin-wins-over-command:  → built-in OpenAI handler fires; stt.providers.openai: type: command
                              does NOT hijack it

Why both surfaces in one PR

The TTS hook (#31745, merged today) shipped on top of an existing TTS command-provider registry (#17843, May 2026). For symmetry, the STT story needs both surfaces. 3 of the 4 in-flight community STT PRs (OpenRouter STT #25721/#24703, SenseAudio #9380) are plain HTTPS APIs that could be served by a shell command. Only Gemini-STT #21540 genuinely needs the Python hook. Shipping both at once means no second PR cycle and no contributor gets told "your work isn't useful, we picked the other path."

How this unblocks the 4 in-flight community PRs

After this lands, each becomes a small focused contribution:

Out of scope

• No picker integration (TOOL_CATEGORIES["transcription"]) — STT isn't surfaced in hermes tools today. Deferred to a follow-up that lands alongside the first community plugin.
• No changes to the 6 built-in STT backends — they stay inline.
• No changes to gateway voice-message auto-transcription — gateway/run.py and gateway/platforms/discord.py call transcribe_audio(), signature unchanged.
• No deprecation of HERMES_LOCAL_STT_COMMAND — preserved via the built-in local_command path.

Related

• PR feat(tts): add register_tts_provider() plugin hook (salvage of #30420) #31745 — register_tts_provider() hook (symmetric TTS surface, just merged)
• PR feat(stt): add register_transcription_provider() plugin hook #30493 — original kshitijk4poor STT plugin hook PR (salvaged into this PR)
• PR feat(tts): add command-type provider registry under tts.providers.<name> #17843 — TTS command-provider registry (architectural template for the new STT registry)
• Issue Add register_tts_provider() plugin hook for Python-SDK and streaming TTS engines #30398 — TTS plugin hook design issue
• Community PRs unblocked: feat(stt): add OpenRouter speech-to-text provider #25721, Feat/openrouter stt provider #24703, feat(stt): add SenseAudio STT provider #9380, feat(voice): add Gemini STT and WhatsApp PTT support #21540

Infographic