llmresilience

type BreakerError struct {
	// RetryAfter is how long until the breaker half-opens.
	RetryAfter time.Duration
}

type Config struct {
	// MaxAttempts is the total number of attempts for establishing the stream
	// (the initial call plus retries). Values < 1 are treated as 1.
	MaxAttempts int
	// BaseBackoff is the backoff before the first retry; it grows exponentially.
	BaseBackoff time.Duration
	// MaxBackoff caps the per-attempt backoff. 0 means no cap.
	MaxBackoff time.Duration
	// PerAttemptTimeout bounds each attempt's establishment (connect + first raw
	// chunk). 0 disables it. It never overrides a shorter caller deadline.
	PerAttemptTimeout time.Duration
	// StreamIdleTimeout bounds the gap between consecutive raw chunks AFTER the
	// first chunk has been observed. 0 disables it. A longer stall is retryable
	// while semantic progress remains precommit and terminal after visible output.
	StreamIdleTimeout time.Duration
	// BreakerThreshold is the number of consecutive failed attempts that opens
	// the breaker. Values < 1 disable the breaker.
	BreakerThreshold int
	// BreakerCooldown is how long the breaker stays open before half-opening.
	BreakerCooldown time.Duration
	// Classifier is a legacy tighten-only retry-policy veto. Typed causal
	// classification runs first; Classifier is consulted only for errors already
	// classified retryable and can refuse another attempt. It cannot upgrade an
	// unknown or permanent error. nil selects DefaultClassifier.
	Classifier func(error) bool
	// Clock returns the current time; injectable for tests. nil selects
	// time.Now.
	Clock func() time.Time
	// Diagnostics is the optional operational-logging sink for stream-lifecycle
	// events (retries, per-attempt timeouts, idle stalls, breaker transitions,
	// exhaustion). nil selects port.NopDiagnostics. This is an ADAPTER seam — it is
	// NOT the loop's run-scoped sink and so is NOT subject to the loop's three-line
	// budget (see docs/adr/0020-diagnostics.md): the wrapper is per-provider and
	// logs provider-level lifecycle. It sees only port.LLMRequest + errors, never
	// prompt text, so every emitted record is metadata-only.
	Diagnostics port.Diagnostics
}

type ExhaustedError struct {
	// Attempts is how many attempts were made.
	Attempts int
	// Err is the final underlying error.
	Err error
	// PerAttempt is the per-attempt establishment budget that was in force, used to
	// name the timeout duration in the operator-facing message. 0 when unset.
	PerAttempt time.Duration
}

type StreamIdleError struct {
	// Idle is the configured idle budget that elapsed without a chunk.
	Idle time.Duration
}