Package com.tnsai.exceptions

Class TnsAIException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

com.tnsai.exceptions.TnsAIException

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

ActionExecutionException, AgentValidationException, ApprovalRequiredException, CommunicationViolationException, GroupPolicyViolationException, IdempotencyException, InvariantViolationException, KnowledgeBaseException, LifecycleManager.LifecycleException, LifecycleManager.LifecycleTimeoutException, LLMException, MessageCallbackDispatcher.CallbackInvocationException, NetworkException, OutputSerializationException, ParseException, PromptException, RateLimitException, RoleAssignmentException, RoleInitializationException, SecurityException, StateException, TaskCompleteException, TimeoutException, ToolException, ValidationException

public class TnsAIException
extends RuntimeException

Base exception for all TnsAI framework exceptions. Provides common functionality like retry classification, error code, thrown-at timestamp, and auto-captured framework EventContext.

Every instance auto-captures the AgentContext.currentOptional() thread-local at construction (issue #90). When operators see the exception in a log they get the agent / role / session / tenant scope inline — no MDC / log archaeology required.

See Also:

• Serialized Form

Constructor Summary

Constructors

Constructor	Description
TnsAIException(String message)
TnsAIException(String message, boolean retryable)
TnsAIException(String message, Throwable cause)
TnsAIException(String message, Throwable cause, boolean retryable)

Method Summary

Modifier and Type	Method	Description
Optional<EventContext>	getContext()	Framework EventContext captured at construction time, if any.
String	getErrorCode()	Gets the error code for this exception type.
int	getMaxRetryAttempts()	Gets maximum recommended retry attempts.
String	getMessage()	Returns the message with the captured EventContext appended in a compact, operator-readable form:
long	getSuggestedRetryDelayMs()	Gets suggested retry delay in milliseconds.
Instant	getThrownAt()	Wall-clock instant the exception was constructed.
boolean	isRetryable()	Checks if this error is retryable.
static TnsAIException	wrap(Throwable t)	Wrap an arbitrary throwable in a TnsAIException so it carries a framework error code, retryable flag, and (via subclassing) flows uniformly through ErrorEmitter.

Methods inherited from class java.lang.Throwable

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

TnsAIException

public TnsAIException(String message)

TnsAIException

public TnsAIException(String message,
 Throwable cause)

TnsAIException

public TnsAIException(String message,
 boolean retryable)

TnsAIException

public TnsAIException(String message,
 Throwable cause,
 boolean retryable)

Method Details

isRetryable

public boolean isRetryable()

Checks if this error is retryable. Retryable errors are typically transient (network issues, rate limits, server errors).

Returns:

true if the operation can be retried

getErrorCode

public String getErrorCode()

Gets the error code for this exception type. Format: TNSAI-XXX where XXX is derived from class name.

getSuggestedRetryDelayMs

public long getSuggestedRetryDelayMs()

Gets suggested retry delay in milliseconds. Override in subclasses for specific retry strategies.

getMaxRetryAttempts

public int getMaxRetryAttempts()

Gets maximum recommended retry attempts.

getThrownAt

public Instant getThrownAt()

Wall-clock instant the exception was constructed. Useful for downstream ErrorReport.timestamp fidelity (the report can be built later than the throw, e.g. inside a higher-up catch block).

Since:

0.5.0 (issue #90)

getContext

public Optional<EventContext> getContext()

Framework EventContext captured at construction time, if any. Empty when the exception was constructed outside an AgentContext.enter(EventContext) scope (test harness, one-off main, third-party-thread). Once set, the context is frozen — later changes to AgentContext.current() do not reach back.

Since:

0.5.0 (issue #90)

getMessage

public String getMessage()

Returns the message with the captured EventContext appended in a compact, operator-readable form:

"<original message> [agent=A1, role=R, session=S, tenant=T]"

Only the populated low-cardinality fields are included; missing ones are skipped so the suffix stays compact. When no context was captured, the original message is returned unchanged so existing log scrapers see the same prefix.

Overrides:

getMessage in class Throwable

Since:

0.5.0 (issue #90)

wrap

public static TnsAIException wrap(Throwable t)

Wrap an arbitrary throwable in a TnsAIException so it carries a framework error code, retryable flag, and (via subclassing) flows uniformly through ErrorEmitter. If t is already a TnsAIException it is returned unchanged.

Best-effort retryable classification: known-transient causes (IOException, SocketTimeoutException, TimeoutException) are marked retryable; others default to non-retryable.

Used at framework boundaries that catch third-party throwables and need a uniform internal type. Consumers should generally throw the original exception or a domain-specific TnsAIException subclass — this wrapper is for defensive infrastructure code.

Since:

0.5.0 (issue #86)