# `MingaAgent.SessionListing`
[🔗](https://github.com/jsmestad/minga/blob/main/lib/minga_agent/session_listing.ex#L1)

A registered agent session and the result of its metadata query.

The session manager owns the stable ID and PID. Metadata belongs to the session process and can be temporarily unavailable without changing that registration. Unavailable reasons are deliberately small and safe to expose through public listing APIs.

# `details`

```elixir
@type details() ::
  {:available, MingaAgent.SessionMetadata.t()}
  | {:unavailable, unavailable_reason()}
```

Metadata query result for a registered session.

# `t`

```elixir
@type t() :: %MingaAgent.SessionListing{
  details: details(),
  id: String.t(),
  pid: pid()
}
```

# `unavailable_reason`

```elixir
@type unavailable_reason() :: :timeout | :unreachable | :invalid_details
```

A safe public reason for unavailable session metadata.

# `available`

```elixir
@spec available(String.t(), pid(), term()) :: t()
```

Creates a listing with available metadata when its ID matches the registration.

# `details`

```elixir
@spec details(t()) :: details()
```

Returns available metadata or the safe reason that it is unavailable.

# `identity`

```elixir
@spec identity(t()) :: {String.t(), pid()}
```

Returns the stable registration identity.

# `read`

```elixir
@spec read(String.t(), pid()) :: t()
```

Reads metadata for a registered session without changing its registration.

# `unavailable`

```elixir
@spec unavailable(String.t(), pid(), unavailable_reason()) :: t()
```

Creates a listing whose metadata is unavailable for a safe public reason.

---

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