Package com.tnsai.resilience

package com.tnsai.resilience

Resilience patterns for fault-tolerant agent and action execution.

Two layers

This package houses two distinct concerns sharing the "resilience" label:

1. Agent-level orchestration (ResilienceExecutor, RetryPolicy) — wraps Agent.chat / tool-call paths with resilience4j-backed circuit breaker, bulkhead, rate limiter, and retry around the orchestration layer. Reads Resilience.
2. Action-level decorators (the TracedResolver / MeteredResolver / FallbackResolver family — issue #173 Phase 1) — wraps individual @ActionSpec dispatches with observability + recovery decorators driven by Traced, Metered, and Fallback. Wired into ActionExecutor immediately around each action's executor invocation; runs in canonical order: Traced → Metered → action → Fallback.

The two layers are intentionally separate: agent-level resilience runs across many actions per chat turn, while action- level decorators are per-dispatch and need different state isolation guarantees. A future Phase 2+ may rationalise them once @Idempotent support lands.

Action-level Phase 1 scope (#173)

Only the three decorators that don't require external storage are wired today — same boundary as the other Phase-1 batches in this sprint (#171 / #172 / #177).

Related Packages

Package	Description
com.tnsai	TnsAI Java SDK - A multi-agent framework with BDI architecture and Gaia methodology.
com.tnsai.resilience.dlq	Dead letter queue for capturing and replaying failed agent messages.
com.tnsai.resilience.recovery	Agent failure detection, health tracking, and automated recovery.

Class	Description
FallbackResolver	Resolves the @Fallback annotation on a Role's methods and invokes the matching handler when an action's primary execution fails.
FallbackResolver.RetryCallback	Callback for re-invoking the primary action during retry.
FallbackStrategy<T>	Functional contract for providing fallback values when an operation ultimately fails.
MeteredHandle	Per-invocation handle for a @Metered action — opened by MeteredResolver.start(com.tnsai.metadata.ActionMetadata, com.tnsai.roles.Role) immediately before action dispatch and closed in a finally block.
MeteredResolver	Resolves the @Metered annotation on an action method or its declaring Role class and produces a MeteredHandle to wrap the dispatch.
ResilienceConfig	Programmatic resilience policy for a builder-built Role — the builder-path counterpart of the @Resilience annotation (TNS-567).
ResilienceConfig.Builder	Fluent builder.
ResilienceExecutor	Central executor that combines retry policies, circuit breaker, bulkhead, rate limiting and dead-letter queue tracking.
ResilienceMetrics	In-memory metrics registry for @Metered actions (issue #173, Phase 1).
ResilienceMetrics.MetricSnapshot	Immutable snapshot of one metric's state at the moment ResilienceMetrics.snapshot(java.lang.String) was called.
ResilienceRequest<T>	Immutable descriptor for executing an operation through the resilience pipeline.
ResilienceRequest.Builder<T>
RetryPolicy	Immutable retry policy definition used by the resilience layer.
RetryPolicy.Builder
TracedResolver	Resolves the @Traced annotation on an action method or its declaring Role class and produces a TracedSpan that wraps the dispatch with structured trace logs.
TracedSpan	Per-invocation handle for a @Traced action — opened by TracedResolver.open(com.tnsai.metadata.ActionMetadata, com.tnsai.roles.Role, java.util.Map<java.lang.String, java.lang.Object>) immediately before dispatch and closed in a finally block.