Skip to content

feat(cli): contextual fallback hints on provider failure#48

Open
anhermon wants to merge 1 commit into
devfrom
feature/anga-577-fallback-hints
Open

feat(cli): contextual fallback hints on provider failure#48
anhermon wants to merge 1 commit into
devfrom
feature/anga-577-fallback-hints

Conversation

@anhermon

@anhermon anhermon commented Apr 5, 2026

Copy link
Copy Markdown
Owner

Thinking Path

  1. Anvil project → CLI binary (crates/cli)
  2. Provider selection in run.rs and eval.rs commands
  3. Error handling path when provider fails (creation or runtime)
  4. HarnessError variants: Provider, Config, Api
  5. User sees raw error with no guidance on what to try next
  6. Need: contextual hint appended to error message based on which backend failed
  7. Solution: provider_fallback_hint() function in commands/mod.rs, applied at error boundaries

What Changed

  • Added provider_fallback_hint(backend) in crates/cli/src/commands/mod.rs — returns a contextual suggestion string based on the failing provider
  • run.rs: wrapped provider creation error, streaming error, and agent run error with fallback hints
  • eval.rs: wrapped provider creation error and agent run error with fallback hints
  • Added 4 unit tests covering cc, claude-code, claude, and echo hint behavior

Verification

  • cargo test --workspace — all tests pass (14 CLI tests including 4 new)
  • cargo clippy -- -D warnings — clean
  • cargo fmt — applied
  • Manual verification: when cc fails → "Hint: Try --provider claude with ANTHROPIC_API_KEY set"
  • Manual verification: when claude fails → "Hint: Set ANTHROPIC_API_KEY or try --provider echo for testing"
  • Echo provider returns no hint (no fallback needed)

Risks

Low risk — only appends text to existing error messages. No behavioral changes to success paths. No new dependencies.

Checklist

  • cargo test passes locally
  • cargo clippy -- -D warnings is clean
  • cargo fmt has been run
  • New behaviour has a test (using EchoProvider where possible)
  • Commit messages follow Conventional Commits
  • The PR description explains why, not just what

Closes ANGA-577

When a provider fails, the error now includes a hint suggesting
alternative providers or env vars to try:
- cc/claude-code failure → suggests --provider claude with ANTHROPIC_API_KEY
- claude/API failure → suggests setting ANTHROPIC_API_KEY or --provider echo

Hints are contextual: only shown when the provider actually fails,
never on success or for echo provider.

Closes ANGA-577

Co-Authored-By: Paperclip <noreply@paperclip.ing>

@anhermon anhermon left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CTO Review — Approve

Clean contextual fallback hints. 4 unit tests cover all match branches. Low risk — only error paths touched.

Suggestions for follow-up:

  1. Extract repeated .map_err closure into fn with_hint(e, backend) helper
  2. Catch-all _ arm assumes Anthropic — add comment or use explicit match arms for future providers

Non-blocking. ✅

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant