Configure built-in retries across execution paths

retry_exhausted_error.go

@@ -0,0 +1,49 @@
+package promptkit
+
+import "fmt"
+
+// RetryExhaustedError reports a built-in generation sequence whose positive
+// transient retry budget ended with an eligible provider status. Its cause
+// remains available through Unwrap, including GenerationError accessors.
+// Engine-produced values are immutable. Default and Go-syntax formatting
+// redact provider details, and there is no stable JSON representation.
+type RetryExhaustedError struct {
+	attempts uint64
+	cause    error
+}
+
+func newRetryExhaustedError(attempts uint64, cause error) *RetryExhaustedError {
+	return &RetryExhaustedError{attempts: attempts, cause: cause}
+}
+
+// Attempts returns the number of model attempts actually dispatched.
+func (e *RetryExhaustedError) Attempts() uint64 {
+	if e == nil {
+		return 0
+	}
+	return e.attempts
+}
+
+// Error returns a redacted diagnostic. It is safe on a nil receiver.
+func (e *RetryExhaustedError) Error() string {
+	if e == nil || e.attempts == 0 {
+		return ErrRetriesExhausted.Error()
+	}
+	return fmt.Sprintf("%s after %d attempts", ErrRetriesExhausted, e.attempts)
+}
+
+// GoString returns the same redacted diagnostic as Error.
+func (e *RetryExhaustedError) GoString() string { return e.Error() }
+
+// Unwrap returns the final failure cause, if present.
+func (e *RetryExhaustedError) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.cause
+}
+
+// Is matches ErrRetriesExhausted, including on nil and zero values.
+func (e *RetryExhaustedError) Is(target error) bool {
+	return target == ErrRetriesExhausted
+}