Package at.aimon.session.web.inbox

Class InboundMessage

java.lang.Object
at.aimon.session.web.inbox.InboundMessage
public final class InboundMessage extends Object
Immutable envelope appended to a ConversationInbox.

An InboundMessage carries everything the holder node needs to start (or inject mid-turn) a turn for a conversation it did not originally receive: target ConversationId, the agentRef the requester targeted (validated against the conversation's binding per design §3.6), the raw user input, priority tier, optional idempotency key, the Principal that initiated the input, and arbitrary string metadata.

Notably absent from this envelope is agentExecutionContextId: the deliver-side context id is meaningless on the holder side, and including it here would only enable accidental misuse. Holder rewraps the user input as a QueuedInput with its own session's ctxId before forwarding to the session's internal queue (design §5.6.3).

Construction is via the nested InboundMessage.Builder. The id is supplied by the inbox implementation at deliver time and assigned through the builder before build().

  • Method Details

    • builder

      public static InboundMessage.Builder builder()

    • getId

      public Optional<InboundMessageId> getId()
      Returns the inbox-assigned id.

      Callers building an envelope to deliver() may leave this unset — the inbox implementation issues the id at delivery time and the manager observes it via ConversationInbox.deliver's return value. After collect(), the id is always present.

      Returns:
      the id, or Optional.empty() when the envelope has not yet been stamped by an inbox

    • getConversationId

      public at.aimon.core.agent.conversation.ConversationId getConversationId()

    • getAgentRef

      public String getAgentRef()

    • getUserInput

      public String getUserInput()

    • getPriority

      public at.aimon.core.agent.queue.QueuedInputPriority getPriority()

    • getIdempotencyKey

      public Optional<String> getIdempotencyKey()

    • getInitiator

      public at.aimon.core.base.Principal getInitiator()

    • getDeliveredAt

      public Instant getDeliveredAt()

    • getMetadata

      public Map<String,String> getMetadata()

    • getSubmitOptions

      public at.aimon.core.agent.SubmitOptions getSubmitOptions()
      Per-turn SubmitOptions preserved end-to-end from WebSubmitRequest so the holder-side dispatch forwards the original caller-supplied executor metadata when it eventually calls session.submitAsync(input, submitOptions, listener). Defaults to SubmitOptions.empty() when the producer did not supply any.

      Codec note: all four built-in inbox codecs (in-memory, Redis, Postgres, MongoDB) round-trip this field. Heterogeneous Map<String, Object> values inside systemPromptVariables / executionAttributes / userInfo.metadata are best-effort across persistent backends: scalar types (String, Number, Boolean, Date) and nested Map/List of those round-trip cleanly; custom POJOs surface as nested Map on the consumer side because the wire format is JSON / BSON without polymorphic type information.