fix(aux): use auth_type-aware error message for missing credentials (#56810)

[Tranquil-Flow]

What

Fixes a misleading RuntimeError raised by the auxiliary client when an explicit provider's client build fails. The existing message hardcoded a <X>_API_KEY environment variable that does not exist for non-API-key providers (vertex ADC, bedrock AWS SDK, oauth_device_code, external_process), pointing users at a nonexistent remediation and blocking diagnosis.

Why

Issue #56810 reports: configuring auxiliary.compression.provider: vertex with no GCP credentials raises "Set the VERTEX_API_KEY environment variable" — but VERTEX_API_KEY does not exist. The user needs to run gcloud auth application-default login (or set GOOGLE_APPLICATION_CREDENTIALS, or configure vertex credentials in config.yaml).

Same bug class affects bedrock (AWS credentials, not API key), oauth-* providers (hermes model to authorize), and external-process backends (binary on PATH).

How

New helper _aux_missing_credentials_error(provider_id) in agent/auxiliary_client.py:

1. Looks up the provider's auth_type in PROVIDER_REGISTRY (defensive try/except — never raises)
2. Returns a RuntimeError with an actionable message for the actual auth mechanism:
   • api_key → existing "Set the X_API_KEY environment variable" message (preserved)
   • vertex → "gcloud auth application-default login / GOOGLE_APPLICATION_CREDENTIALS / vertex config"
   • aws_sdk → "aws configure / AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY / IAM roles / SSO"
   • oauth_device_code / oauth_external → "hermes model to authorize"
   • external_process → "verify the binary is installed and on PATH"
   • unknown / unregistered auth_type → safe generic message that does not lie about API keys

Both raise sites (sync call_llm at line 6022 and async async_call_llm at line 6592) replaced with raise _aux_missing_credentials_error(_explicit).

The configured-fallback path (_try_configured_fallback_for_unavailable_client) is preserved as-is — when a fallback chain is configured, the fallback is still tried first, only the error after fallback-exhaustion gets the new message.

Tests

tests/agent/test_auxiliary_auth_type_hint_56810.py — 8 regression tests, all production-path (mock _get_cached_client to return (None, None), drive real call_llm / async_call_llm):

• TestVertexAuxClientErrorMessage — vertex + bedrock × sync + async (4 tests, parameterized)
• TestApiKeyProviderStillHelpful — openai + anthropic still get the existing "Set X_API_KEY" message (2 tests)
• TestUnknownAuthTypeStillActionable — unknown auth_type does NOT lie about API keys (1 test)
• TestFallbackChainStillWorks — fallback chain still takes precedence over the error (1 test)

Verified

• RED (independent): git checkout 88d1d6206f -- agent/auxiliary_client.py then run new tests → 5 of 8 fail with BEDROCK_API_KEY / VERTEX_API_KEY / CUSTOM-FUTURE-PROVIDER_API_KEY in error messages (3 regression guards correctly pass on the buggy code)
• GREEN (with fix): 8 of 8 pass in 0.38s
• Broader regression: 298 passed in test_auxiliary_client.py + test_compress_focus.py + test_compression_concurrent_fork.py. One unrelated flake (TestCodexAuxiliaryAdapterTimeout::test_enforces_total_timeout_while_stream_keeps_emitting_events) — pre-existing on upstream/main, confirmed by retry.

Files

• agent/auxiliary_client.py — +75/-10 (1 helper + 2 raise-site swaps)
• tests/agent/test_auxiliary_auth_type_hint_56810.py — new file, +266 lines (8 regression tests)

Out of scope

• Vision path verified unaffected (resolve_vision_provider_client has its own (correct) message)
• Fallback-chain logic untouched
• No changes to PROVIDER_REGISTRY itself (this fix is a consumer of the registry's auth_type field; the data must be populated by provider-registration PRs like fix(vertex,moa): register vertex in PROVIDER_REGISTRY and HERMES_OVERLAYS #56688)

Competitor analysis

No open PR addresses the same misleading-error symptom. Closest work in this area:

• #56688 — registers vertex in PROVIDER_REGISTRY (complementary — makes the lookup succeed)
• #56809 — vertex model-name prefix (unrelated)
• #56820 — provider model normalization (unrelated)

Auto-published by Moonsong via Path B automated pipeline.

[Tranquil-Flow]

Author-email amend (force-push 6d2ba6ebe4 → 2ea0931cdc): the original commit was authored as tranquil-flow@users.noreply.github.com which is not in scripts/release.py AUTHOR_MAP. Fixed to 66773372+Tranquil-Flow@users.noreply.github.com to clear the Check contributors / check-attribution check. No code changes — same diff, same tests, same fix.

[alt-glitch]

This was generated by AI during triage.

Duplicate of #56842 (earlier open PR) — both fix #56810 by adding an auth_type-aware missing-credentials error helper in agent/auxiliary_client.py, replacing the hardcoded <X>_API_KEY message at the same two raise sites. #56842 is the canonical (earliest); a maintainer should pick one.

[teknium1]

Thanks for covering both synchronous and asynchronous auxiliary error paths; current main still has the misleading hardcoded message at agent/auxiliary_client.py:6725 and :7345.

Problems

• The new lookup at agent/auxiliary_client.py:5859 only reads PROVIDER_REGISTRY. Current main's extension loop admits only api_key profiles (hermes_cli/auth.py:447-477), while the bundled Vertex profile is auth_type="vertex" (plugins/model-providers/vertex/__init__.py:65-73). Consequently, Vertex falls through to the helper's generic message instead of the proposed ADC guidance.
• The new tests inject a fake registry containing Vertex, so they do not cover this production registry gap.

Suggested changes

• Fall back to the canonical provider-profile lookup when PROVIDER_REGISTRY has no entry, or include the required Vertex registry registration; then add a regression using the real registry path.

Automated hermes-sweeper review.

[teknium1]

PROVIDER_REGISTRY does not contain Vertex on current main: its auto-extension skips all non-api_key profiles (hermes_cli/auth.py:455), even though the bundled Vertex profile declares auth_type="vertex". This makes the reported Vertex case take the generic branch rather than the ADC-specific branch. Please fall back to the canonical provider-profile registry here, or add the corresponding Vertex registry admission and cover it without a fake registry.