Package com.tnsai.exceptions

Class ContextualWrapper

java.lang.Object
java.lang.Throwable
java.lang.Exception
java.lang.RuntimeException
com.tnsai.exceptions.ContextualWrapper
All Implemented Interfaces:
Serializable
public class ContextualWrapper extends RuntimeException
Thin RuntimeException that wraps a non-TnsAIException throwable so its EventContext is preserved at the catch site.

Third-party libraries (OkHttp, Jackson, Jedis, Playwright, …) throw their own exception types that don't extend TnsAIException and therefore can't auto-capture AgentContext at construction. When the framework catches one at a boundary (action executor, LLM client, MCP client) and wants to surface it to operators with the same correlation fields a TnsAIException would carry, it goes through ThrowableContextDecorator.enrich(Throwable) which produces a ContextualWrapper.

The wrapper:

  • Captures the current thread's AgentContext at the wrap-time boundary.
  • Delegates Throwable.getCause() to the original throwable so the full root-cause stack is preserved.
  • Includes the captured context in getMessage() the same way TnsAIException does so log scrapers see it inline.
  • Does not extend TnsAIException on purpose — consumers catching TnsAIException should not start matching wrapped third-party throwables they previously did not match. Pattern- matching for wrapped errors is explicit: if (t instanceof ContextualWrapper w) { ... }.
Since:
0.5.0 (issue #90)
See Also:

  • Constructor Details

    • ContextualWrapper

      public ContextualWrapper(Throwable original)
      Wrap original with the current thread's AgentContext (which may be empty).

    • ContextualWrapper

      public ContextualWrapper(Throwable original, EventContext explicitContext)
      Wrap original with an explicit context (test / cross-thread scenarios where the natural thread-local lookup is wrong).

  • Method Details