Wrap provider SDK errors in gai-native error types

[maragubot]

Problem

Currently, errors from the provider clients (clients/anthropic, clients/openai, clients/google) bubble up as the raw SDK error types wrapped with fmt.Errorf. This leaks SDK-specific shapes into downstream code: any package that wants to introspect errors (HTTP status, rate-limit hints, request IDs, model refusals, etc.) has to import the underlying SDK.

Concrete example surfaced by the robust package (#209): its DefaultErrorClassifier cannot call into *anthropic.Error.StatusCode, *openai.Error.StatusCode, or genai.APIError.Code without importing all three SDKs, which would force every adopter of robust to depend on all three. The current workaround is regex-based string inspection of the error message — functional but brittle and uninformative.

Proposed direction

Wrap every client error at the boundary into a gai-native error type that exposes the information we care about via small, stable interfaces. Rough sketch:

// In gai or a new gai/errors subpackage:
type StatusCoder interface { error; StatusCode() int }
type RequestIDer interface { error; RequestID() string }
// ... other capability-style interfaces as needed

// Each client wraps SDK errors into a concrete type that implements the relevant interfaces.

Consumers then use errors.As (or errors.AsType once Go 1.26 is the floor) against the interfaces, never against SDK concrete types. The SDK error remains reachable via errors.Unwrap as an escape hatch.

Benefits

• robust.DefaultErrorClassifier becomes precise and SDK-agnostic — drop the regex.
• Downstream consumers (logging, metrics, custom retry policies, error reporting to users) get a uniform surface.
• Keeps the minimal-abstraction spirit: SDK errors are still unwrappable for escape-hatch access.

Open questions

• Which information is worth surfacing on v1? Candidates: HTTP status, request ID, rate-limit hint (if providers supply it), model refusal flag, provider name.
• One top-level error type with multiple interface implementations, vs. several distinct types.
• Whether to also normalize to typed errors that can be compared with errors.Is (e.g. ErrRateLimited, ErrAuthentication).

References

• PR Add robust chat completer with retries and fallbacks #209 (robust chat completer) — the immediate motivator; see robust/classify.go for the regex workaround that this issue would let us delete.