fix(agent): normalize provider failures

[sentry-junior]

summary

• add a structured ProviderError contract for provider/auth/capacity/rate-limit/network failures
• preserve status, provider/model, retry/fallback eligibility, retry hints, bounded upstream diagnostics, and safe user copy
• replace Error.name retry signaling with typed fields
• carry normalized failures into turn diagnostics and Sentry attributes
• show actionable terminal provider messages while retaining the event id

context

This is the first vertical slice from the provider-error investigation prompted by recurring xAI 503 capacity failures (JUNIOR-53). Gateway fallback configuration remains separate work.

tests

• added focused coverage for xAI 503 normalization, retry hints, and safe user-facing capacity responses
• git diff --check passes
• local tests/typecheck are currently unverified: the checkout had no dependencies, and pnpm install --frozen-lockfile was cancelled by the runtime before completion

Requested by immutable dcramer via Junior.

--

View Junior Session in Sentry

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
junior-docs	Ready	Preview	Jul 15, 2026 6:38pm

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 22698f0. Configure here.}

[cursor]

Overbroad safety error classification

Medium Severity

classifyProviderError treats any message containing bare safety as content_policy, which is non-retryable. Transient provider failures whose text happens to include that word are therefore dropped from retry/fallback even when status or other signals indicate a temporary outage.

 

^{Reviewed by Cursor Bugbot for commit 22698f0. Configure here.}

[cursor]

Thrown failures skip normalization

Medium Severity

The agent catch path stores the raw thrown value as providerError, while finalizeFailedTurnReply only emits actionable copy and provider attributes when that value is a ProviderError. buildTurnResult normalizes via createProviderError, so transport throws that never become assistant stopReason: "error" messages still get the generic terminal reply and empty provider telemetry.

Additional Locations (2)

• packages/junior/src/chat/services/turn-failure-response.ts#L147-L154
• packages/junior/src/chat/services/turn-result.ts#L390-L394

 

^{Reviewed by Cursor Bugbot for commit 22698f0. Configure here.}