# `AgentSessionManager.Core.Event`
[🔗](https://github.com/nshkrdotcom/agent_session_manager/blob/v0.8.0/lib/agent_session_manager/core/event.ex#L1)

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)

# `event_type`

```elixir
@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
```

# `t`

```elixir
@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
}
```

# `all_types`

```elixir
@spec all_types() :: [event_type()]
```

Returns all valid event types.

# `approval_events`

```elixir
@spec approval_events() :: [event_type()]
```

Returns approval event types.

# `error_events`

```elixir
@spec error_events() :: [event_type()]
```

Returns error event types.

# `from_map`

```elixir
@spec from_map(map()) :: {:ok, t()} | {:error, AgentSessionManager.Core.Error.t()}
```

Reconstructs an event from a map.

# `message_events`

```elixir
@spec message_events() :: [event_type()]
```

Returns message event types.

# `new`

```elixir
@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}}

# `policy_events`

```elixir
@spec policy_events() :: [event_type()]
```

Returns policy event types.

# `run_events`

```elixir
@spec run_events() :: [event_type()]
```

Returns run lifecycle event types.

# `session_events`

```elixir
@spec session_events() :: [event_type()]
```

Returns session lifecycle event types.

# `to_map`

```elixir
@spec to_map(t()) :: map()
```

Converts an event to a map suitable for JSON serialization.

# `tool_events`

```elixir
@spec tool_events() :: [event_type()]
```

Returns tool event types.

# `valid_type?`

```elixir
@spec valid_type?(atom()) :: boolean()
```

Checks if the given type is a valid event type.

# `workspace_events`

```elixir
@spec workspace_events() :: [event_type()]
```

Returns workspace event types.

---

*Consult [api-reference.md](api-reference.md) for complete listing*