Alloy.Events (alloy v0.12.4)

Copy Markdown View Source

Event envelope construction and runtime opts normalization.

Builds v1 event envelopes, manages sequence counters, and derives correlation IDs. Used by Alloy.Agent.Turn to wrap raw provider and tool events into the versioned envelope shape exposed to :on_event callbacks on Alloy.run/2 and Alloy.stream/3.

The v1 envelope is part of the protocol surface — anything Turn emits is something downstream consumers can rely on. :telemetry events fired alongside the envelope are the lower-level analogue.

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.