fix(stt): surface the selection-specific error for explicit openai STT

[liuhao1024]

What does this PR do?

Makes an explicit stt.provider: openai selection report its real blocker instead of generic setup guidance. When the managed openai-audio gateway is unavailable, _resolve_openai_audio_client_config() already raises a ValueError that names the blocker and — for managed-Nous users — appends the hermes tools remediation. But the explicit-openai branch of _get_provider() checked availability through the boolean _has_openai_audio_backend() probe, which flattens that ValueError into False. The log then claimed "STT provider 'openai' configured but no API key available" and the transcription result fell through to the all-provider "No STT provider available. Install faster-whisper … set GROQ_API_KEY …" hint — directing operators toward unrelated provider setup when their managed route is what's down.

Two changes, both in the explicit-selection path (auto-detect is untouched):

• _get_provider() resolves _resolve_openai_audio_client_config() directly (same gate: _HAS_OPENAI + the resolver succeeding ≡ the old probe), so the warning names the actual blocker instead of a bare API-key hint.
• _dispatch_stt_provider()'s "none" fallback re-resolves the config when the config explicitly chose openai and returns its ValueError message as the transcription error. The generic all-provider hint remains the answer for auto-detect with no credentials.

No fallback is added — an unavailable selection still resolves to none; it just says why.

Related Issue

Fixes #93045

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)

Changes Made

• tools/transcription_tools.py
  • _get_provider() explicit openai branch: replace the _has_openai_audio_backend() probe with a direct _resolve_openai_audio_client_config() call in a try/except so the warning carries the selection-specific message (comment names the probe-flattening mechanism)
  • _dispatch_stt_provider() "No provider available" fallback: when the config explicitly chose openai and the package is present, re-resolve and return the selection-specific error dict instead of the all-provider install hint (comment marks the explicit-choice-only guard)
• tests/tools/test_transcription_tools.py
  • new TestExplicitOpenaiSelectionError class: _get_provider names the managed-route blocker (and not "no API key") when the managed gateway is down; the dispatch result carries the hermes tools remediation (and not the generic hint) for an explicit openai choice; auto-detect with no credentials still gets the generic hint (guard against over-firing)

How to Test

1. .venv/bin python -m pytest tests/tools/test_transcription_tools.py -q
2. Observed result: all provider-selection and dispatch tests pass (50 passed in the full file on a warm env; 4 pre-existing environment failures — psutil/model-correction mocks — reproduce identically on unmodified main and are unrelated). Reverting only tools/transcription_tools.py makes exactly the two selection-specific tests fail (2 failed, 1 passed), confirming they pin the new reporting.
3. Manual check matching the issue's repro: configure stt.provider: openai, clear VOICE_TOOLS_OPENAI_KEY/OPENAI_API_KEY, and disable the managed openai-audio gateway — a transcription call now returns the selection-specific error naming the managed route (with the hermes tools remediation for managed-Nous users) instead of "No STT provider available. Install faster-whisper …".

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 (full transcription suite; 4 failures reproduce identically on unmodified main — environment deps, not this diff)
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: macOS 15 (Apple Silicon)

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A (inline comments name the mechanism)
• 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 (pure Python error-propagation change)
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

[Enough1122]

AI code review — automated review for reference, author can ignore or act on any point.

Correct diagnosis: flattening _resolve_openai_audio_client_config's selection-specific ValueError into a boolean probe turned a managed-route outage into "no API key" guidance, sending operators down the wrong path. The fix surfaces the real reason at both the provider-resolution and dispatch layers, and the tests pin all three behaviors (explicit selection error, dispatch error text, auto-detect unaffected). Two notes:

1. tools/transcription_tools.py:3172-3179 — the dispatch-level re-probe calls _resolve_openai_audio_client_config() a second time just to recover the message that _get_provider already logged and discarded. If resolution constructs a client or hits config/disk, that's duplicated work per failed transcription, and the two calls can theoretically disagree (config changed between them). Consider threading the specific failure through (e.g., a module-level "last openai selection failure" or returning (provider, reason) from _get_provider) instead of re-resolving.

2. tools/transcription_tools.py:3148 — the new branch requires str(stt_config.get("provider")) == "openai" exactly; an explicit "openai" set via the STT config file but normalized differently upstream (case/whitespace) would silently miss the specific-error path. A .strip().lower() on both sides is cheap insurance given the whole point is matching the user's explicit choice.

The negative test asserting auto-detection keeps the generic all-provider hint shows good boundary discipline.

[teknium1]

Merged via #93356 (rebase) — your commit is on main with authorship preserved.