Summary

Describe the problem and fix in 2–5 bullets:

• Problem: when a selected model fails due to missing provider API key, the error is technically correct but not actionable enough (for example, users do not see the exact env var/config key to set).
• Why it matters: model switching in TUI/interactive flows feels broken/confusing and increases setup friction.
• What changed: missing-key errors now include provider-specific env var hints (for example $GEMINI_API_KEY) and the exact config path (models.providers.<provider>.apiKey) to set.
• What did NOT change (scope boundary): auth resolution logic/order is unchanged; this PR only improves missing-key guidance text.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes [Bug]: Warning Message When Selecting a Model with API KEY Not Configured is Not Helpful #31544
• Related fix(agents): recover reasoning-only vLLM OpenAI-compat replies #31746

User-visible / Behavior Changes

• Missing provider API key errors now tell users exactly what to set next (env var + config path), instead of only generic auth-store guidance.

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS (local test run)
• Runtime/container: Node 22 + pnpm
• Model/provider: google, zai missing-key cases
• Integration/channel (if any): N/A
• Relevant config (redacted): default auth store + empty provider key env

Steps

1. Attempt auth resolution for a provider without configured key (for example google).
2. Observe thrown missing-key error.
3. Validate the message includes provider-specific env/config hints.

Expected

• Error includes actionable hints such as $GEMINI_API_KEY and models.providers.google.apiKey.

Actual

• Matches expected with updated tests.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • pnpm test src/agents/model-auth.profiles.test.ts
  • pnpm check
• Edge cases checked:
  • multi-env hint provider (zai) includes both $ZAI_API_KEY and $Z_AI_API_KEY
  • single-env hint provider (google) includes $GEMINI_API_KEY
• What you did not verify:
  • full interactive TUI flow end-to-end on a remote Linux host

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps:

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: revert commit fix(auth): add provider-specific missing-key guidance.
• Files/config to restore: src/agents/model-auth.ts.
• Known bad symptoms reviewers should watch for: unexpected wording regressions in missing-key error messages.

Risks and Mitigations

List only real risks for this PR. Add/remove entries as needed. If none, write None.

• Risk: copy text changes could make tests brittle if message wording changes frequently.
  • Mitigation: tests assert key actionable substrings (env/config hints) instead of full exact message blocks.