Package com.tnsai.context.ephemeral

Class EphemeralContextManager

java.lang.Object
com.tnsai.context.ephemeral.EphemeralContextManager
public class EphemeralContextManager extends Object
Manages ephemeral tool outputs to prevent context explosion.

Tracks tool call results and automatically prunes older results when the configured limit is exceeded.

Usage


 EphemeralContextManager manager = new EphemeralContextManager();

 // Register ephemeral action
 manager.registerAction("getBrowserState", 3);

 // Track tool results
 manager.trackResult("getBrowserState", result1);
 manager.trackResult("getBrowserState", result2);
 manager.trackResult("getBrowserState", result3);
 manager.trackResult("getBrowserState", result4);

 // Get IDs of results to remove from context
 List<String> toRemove = manager.getResultsToRemove("getBrowserState");
 // Returns [result1_id] - oldest result exceeds keepLast=3

Thread Safety

This class is thread-safe and can be used from multiple threads.

Author:
TnsAI Team
See Also:
  • Ephemeral

  • Constructor Details

    • EphemeralContextManager

      public EphemeralContextManager()
      Creates a new ephemeral context manager.

  • Method Details

    • registerAction

      public void registerAction(String actionName, int keepLast)
      Registers an action as ephemeral with the specified keepLast count.
      Parameters:
      actionName - the action name
      keepLast - number of results to keep

    • registerAction

      public void registerAction(String actionName, EphemeralContextManager.EphemeralConfig config)
      Registers an action as ephemeral with full config.
      Parameters:
      actionName - the action name
      config - the ephemeral configuration

    • registerFromMethod

      public void registerFromMethod(Method method)
      Registers an action from its method annotation.
      Parameters:
      method - the method with @Ephemeral annotation

    • isEphemeral

      public boolean isEphemeral(String actionName)
      Checks if an action is registered as ephemeral.
      Parameters:
      actionName - the action name
      Returns:
      true if ephemeral

    • getConfig

      public EphemeralContextManager.EphemeralConfig getConfig(String actionName)
      Gets the configuration for an action.
      Parameters:
      actionName - the action name
      Returns:
      config or null if not ephemeral

    • trackResult

      public EphemeralContextManager.TrackedResult trackResult(String actionName, Object result)
      Tracks a new tool result.
      Parameters:
      actionName - the action name
      result - the result object
      Returns:
      the tracked result with generated ID

    • getResultsToRemove

      public List<String> getResultsToRemove(String actionName)
      Gets the IDs of results that should be removed from context.

      These are the oldest results that exceed the keepLast limit.

      Parameters:
      actionName - the action name
      Returns:
      list of result IDs to remove (empty if none)

    • pruneResults

      public List<EphemeralContextManager.TrackedResult> pruneResults(String actionName)
      Prunes old results for an action.

      Removes results that exceed the keepLast limit.

      Parameters:
      actionName - the action name
      Returns:
      list of removed results

    • pruneAll

      public Map<String,List<EphemeralContextManager.TrackedResult>> pruneAll()
      Prunes all ephemeral actions.
      Returns:
      map of action name to removed results

    • generateSummary

      public String generateSummary(String actionName, int removedCount)
      Generates a summary message for removed results.
      Parameters:
      actionName - the action name
      removedCount - number of removed results
      Returns:
      summary message

    • getResults

      public List<EphemeralContextManager.TrackedResult> getResults(String actionName)
      Gets all tracked results for an action.
      Parameters:
      actionName - the action name
      Returns:
      list of tracked results (oldest first)

    • getResult

      public EphemeralContextManager.TrackedResult getResult(String resultId)
      Gets a specific result by ID.
      Parameters:
      resultId - the result ID
      Returns:
      the tracked result or null

    • getResultCount

      public int getResultCount(String actionName)
      Gets the count of tracked results for an action.
      Parameters:
      actionName - the action name
      Returns:
      result count

    • clearResults

      public void clearResults(String actionName)
      Clears all tracked results for an action.
      Parameters:
      actionName - the action name

    • clearAll

      public void clearAll()
      Clears all tracked results for all actions.

    • getRegisteredActions

      public Set<String> getRegisteredActions()
      Gets all registered ephemeral action names.
      Returns:
      set of action names

    • getStats

      public Map<String,Integer> getStats()
      Gets statistics about tracked results.
      Returns:
      map of action name to result count