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

Represents an AI agent session.

A session is a logical container for a series of runs (interactions)
with an AI agent. It maintains state, context, and metadata across
multiple runs.

## Session Lifecycle

Sessions follow this state machine:

    pending -> active -> completed
                     -> failed
                     -> cancelled
             -> paused -> active (resumed)

## Fields

- `id` - Unique session identifier
- `agent_id` - Identifier for the agent type/configuration
- `status` - Current session status (:pending, :active, :paused, :completed, :failed, :cancelled)
- `parent_session_id` - Optional parent session for hierarchical sessions
- `metadata` - Arbitrary metadata associated with the session
- `context` - Shared context data (system prompts, configuration)
- `tags` - List of tags for categorization
- `created_at` - Session creation timestamp
- `updated_at` - Last update timestamp

## Usage

    # Create a new session
    {:ok, session} = Session.new(%{agent_id: "my-agent"})

    # Update status
    {:ok, active} = Session.update_status(session, :active)

    # Serialize for storage
    map = Session.to_map(session)

# `status`

```elixir
@type status() :: :pending | :active | :paused | :completed | :failed | :cancelled
```

# `t`

```elixir
@type t() :: %AgentSessionManager.Core.Session{
  agent_id: String.t() | nil,
  context: map(),
  created_at: DateTime.t() | nil,
  deleted_at: DateTime.t() | nil,
  id: String.t() | nil,
  metadata: map(),
  parent_session_id: String.t() | nil,
  status: status(),
  tags: [String.t()],
  updated_at: DateTime.t() | nil
}
```

# `from_map`

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

Reconstructs a session from a map.

# `new`

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

Creates a new session with the given attributes.

## Required

- `:agent_id` - The agent identifier

## Optional

- `:id` - Custom ID (auto-generated if not provided)
- `:parent_session_id` - Parent session for hierarchical sessions
- `:metadata` - Arbitrary metadata map
- `:context` - Shared context data
- `:tags` - List of string tags

## Examples

    iex> Session.new(%{agent_id: "my-agent"})
    {:ok, %Session{agent_id: "my-agent", status: :pending, ...}}

    iex> Session.new(%{})
    {:error, %Error{code: :validation_error, ...}}

# `to_map`

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

Converts a session to a map suitable for JSON serialization.

# `update_status`

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

Updates the session status.

## Valid statuses

- `:pending` - Session created but not started
- `:active` - Session is currently active
- `:paused` - Session is paused
- `:completed` - Session completed successfully
- `:failed` - Session failed
- `:cancelled` - Session was cancelled

## Examples

    iex> {:ok, session} = Session.new(%{agent_id: "agent"})
    iex> Session.update_status(session, :active)
    {:ok, %Session{status: :active, ...}}

    iex> Session.update_status(session, :invalid)
    {:error, %Error{code: :invalid_status}}

---

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