Represents an event in the agent session lifecycle.
Events are immutable records of things that happened during session and run execution. They provide an audit trail and can be used for debugging, analytics, and state reconstruction.
Event Categories
Session Lifecycle Events
:session_created- A new session was created:session_started- Session execution began:session_paused- Session was paused:session_resumed- Session was resumed from pause:session_completed- Session completed successfully:session_failed- Session failed with an error:session_cancelled- Session was cancelled
Run Lifecycle Events
:run_started- A run began execution:run_completed- A run completed successfully:run_failed- A run failed with an error:run_cancelled- A run was cancelled:run_timeout- A run timed out
Message Events
:message_sent- A message was sent to the agent:message_received- A message was received from the agent:message_streamed- A streaming message chunk was received
Tool Events
:tool_call_started- A tool call began:tool_call_completed- A tool call completed:tool_call_failed- A tool call failed
Error Events
:error_occurred- An error occurred:error_recovered- Recovered from an error
Usage Events
:token_usage_updated- Token usage was updated:turn_completed- A conversation turn completed
Workspace Events
:workspace_snapshot_taken- Workspace snapshot was taken:workspace_diff_computed- Workspace diff was computed
Policy Events
:policy_violation- Policy violation was detected during execution
Approval Events
:tool_approval_requested- Tool execution requires human approval:tool_approval_granted- Human approved the tool execution:tool_approval_denied- Human denied the tool execution
Usage
# Create an event
{:ok, event} = Event.new(%{
type: :message_received,
session_id: "session-123",
run_id: "run-456",
data: %{content: "Hello!"}
})
# Serialize for storage
map = Event.to_map(event)Summary
Functions
Returns all valid event types.
Returns approval event types.
Returns error event types.
Reconstructs an event from a map.
Returns message event types.
Creates a new event with the given attributes.
Returns policy event types.
Returns run lifecycle event types.
Returns session lifecycle event types.
Converts an event to a map suitable for JSON serialization.
Returns tool event types.
Checks if the given type is a valid event type.
Returns workspace event types.
Types
@type event_type() ::
:session_created
| :session_started
| :session_paused
| :session_resumed
| :session_completed
| :session_failed
| :session_cancelled
| :run_started
| :run_completed
| :run_failed
| :run_cancelled
| :run_timeout
| :message_sent
| :message_received
| :message_streamed
| :tool_call_started
| :tool_call_completed
| :tool_call_failed
| :error_occurred
| :error_recovered
| :token_usage_updated
| :turn_completed
| :workspace_snapshot_taken
| :workspace_diff_computed
| :policy_violation
| :tool_approval_requested
| :tool_approval_granted
| :tool_approval_denied
@type t() :: %AgentSessionManager.Core.Event{ correlation_id: String.t() | nil, data: map(), id: String.t() | nil, metadata: map(), provider: String.t() | nil, run_id: String.t() | nil, schema_version: non_neg_integer(), sequence_number: non_neg_integer() | nil, session_id: String.t() | nil, timestamp: DateTime.t() | nil, type: event_type() | nil }
Functions
@spec all_types() :: [event_type()]
Returns all valid event types.
@spec approval_events() :: [event_type()]
Returns approval event types.
@spec error_events() :: [event_type()]
Returns error event types.
@spec from_map(map()) :: {:ok, t()} | {:error, AgentSessionManager.Core.Error.t()}
Reconstructs an event from a map.
@spec message_events() :: [event_type()]
Returns message event types.
@spec new(map()) :: {:ok, t()} | {:error, AgentSessionManager.Core.Error.t()}
Creates a new event with the given attributes.
Required
:type- The event type (must be a valid event type):session_id- The session this event belongs to
Optional
:id- Custom ID (auto-generated if not provided):run_id- The run this event belongs to (for run-scoped events):data- Event payload data:metadata- Arbitrary metadata:sequence_number- Sequence number for ordering
Examples
iex> Event.new(%{type: :session_created, session_id: "session-123"})
{:ok, %Event{type: :session_created, ...}}
iex> Event.new(%{type: :invalid_type, session_id: "session-123"})
{:error, %Error{code: :invalid_event_type}}@spec policy_events() :: [event_type()]
Returns policy event types.
@spec run_events() :: [event_type()]
Returns run lifecycle event types.
@spec session_events() :: [event_type()]
Returns session lifecycle event types.
Converts an event to a map suitable for JSON serialization.
@spec tool_events() :: [event_type()]
Returns tool event types.
Checks if the given type is a valid event type.
@spec workspace_events() :: [event_type()]
Returns workspace event types.