Alloy.Agent.Events (alloy v0.10.1)

Event envelope construction and runtime opts normalization.

Builds v1 event envelopes, manages sequence counters, and derives correlation IDs. Extracted from Alloy.Agent.Turn to separate event plumbing from agent loop control flow.

Summary

Functions

build_correlation_id(state)

Derive a correlation ID from the agent state's context.

emit(opts, turn, raw_event)

Emit an event envelope.

normalize_opts(state, opts)

Normalize runtime opts for event emission.

Functions

build_correlation_id(state)

@spec build_correlation_id(Alloy.Agent.State.t()) :: binary()

Derive a correlation ID from the agent state's context.

Precedence: context[:request_id] > context[:correlation_id] > generated from agent_id.

emit(opts, turn, raw_event)

@spec emit(keyword(), non_neg_integer(), term()) :: :ok

Emit an event envelope.

Builds a v1 envelope from the raw event, calls the on_event callback, and fires a :telemetry event.

normalize_opts(state, opts)

@spec normalize_opts(
  Alloy.Agent.State.t(),
  keyword()
) :: keyword()

Normalize runtime opts for event emission.

Ensures :on_event, :event_seq_ref, and :event_correlation_id are present in the opts keyword list.