Package dyntabs.ai.activity

Class UserActivityEvent

java.lang.Object
dyntabs.ai.activity.UserActivityEvent
public final class UserActivityEvent extends Object
One immutable "the user just did something meaningful" entry in the Ambient Activity timeline — the UI → AI counterpart to EasyAIEvent (which is AI → UI).

What this class is for

As a user works inside a TabForge application — opening an order, running a search, jotting a note — each of those acts is captured as one UserActivityEvent and dropped onto a short, per-tab timeline. When the user later asks the assistant something context-dependent ("summarise this", "email that customer"), we render a compact slice of this timeline into the prompt so the assistant already knows what "this" and "that" refer to. The user never has to re-type the context they just clicked through.

Familiar analogy: a flight recorder's event track — not the raw cockpit video, just the labelled milestones: "gear up", "autopilot engaged", "descent started". Each milestone is timestamped, typed, and tagged with what it concerned. When you want to understand the last few minutes, you read this clean track, not hours of footage. A UserActivityEvent is one such milestone, and crucially it is semantic: because we live inside the app we record "opened order #4711", never "clicked pixel (812, 344)".

How the fields are read downstream

type is the coarse category, verb is the specific act in the app's own vocabulary (e.g. "approve", "cancel"), entities are the business objects the act touched (the raw material for resolving "this"/"that"), and text is any free text the user authored (a note or a search query). sessionId and tabId scope the timeline — by default the assistant only sees activity from the current tab and session, which is what makes @TabScoped per-tab memory fall out for free. timestamp orders the timeline.

Instances are created via UserActivityEvent.Builder (typically by the capture layer, not application code) and are immutable, so they are safe to share across threads, queues, or a ring-buffer store.

See Also:

  • Method Details

    • timestamp

      public Instant timestamp()
      Returns:
      when the act happened; never null.

    • sessionId

      public String sessionId()
      Returns:
      the session this act belongs to (scopes the timeline), or null if unscoped.

    • tabId

      public String tabId()
      Returns:
      the tab this act belongs to (per-tab memory partition), or null if none.

    • type

      public UserActivityEvent.Type type()
      Returns:
      the coarse category of the act; never null.

    • verb

      public String verb()
      Returns:
      the specific act in the app's vocabulary (e.g. "approve"), or null.

    • entities

      public List<EntityRef> entities()
      Returns:
      an unmodifiable list of the business objects this act touched; never null (empty when the act concerned no specific entity, e.g. a free search).

    • text

      public String text()
      Returns:
      free text the user authored (a note or a search query), or null.

    • primaryEntity

      public EntityRef primaryEntity()
      Convenience accessor for the entity this act primarily concerned — useful for deixis, where "this" usually means the single most relevant object.
      Returns:
      the first EntityRef, or null if the act touched no entity.

    • builder

      public static UserActivityEvent.Builder builder(UserActivityEvent.Type type)
      Start building an activity event of the given type.
      Parameters:
      type - the coarse category (required)
      Returns:
      a new UserActivityEvent.Builder

    • toString

      public String toString()
      Overrides:
      toString in class Object