# `Backplane.McpProtocol.Server.Session`

Per-client MCP session process.

Each Session is a GenServer that manages the lifecycle of a single MCP client
connection. It handles protocol initialization, request/notification dispatch,
server-initiated requests (sampling, roots), and session persistence.

Sessions are created by the transport layer (STDIO creates one at startup,
HTTP transports create them dynamically via `Backplane.McpProtocol.Server.Supervisor`).

# `t`

```elixir
@type t() :: %{
  session_id: String.t(),
  server_module: module(),
  protocol_version: String.t() | nil,
  protocol_module: module() | nil,
  initialized: boolean(),
  client_info: map() | nil,
  client_capabilities: map() | nil,
  log_level: String.t() | nil,
  frame: Backplane.McpProtocol.Server.Frame.t(),
  server_info: map(),
  capabilities: map(),
  instructions: String.t() | nil,
  supported_versions: [String.t()],
  transport: %{layer: module(), name: GenServer.name()},
  registry: module(),
  session_idle_timeout: pos_integer(),
  expiry_timer: reference() | nil,
  pending_requests: %{
    required(String.t()) => %{started_at: integer(), method: String.t()}
  },
  server_requests: %{
    required(String.t()) => %{method: String.t(), timer_ref: reference()}
  },
  timeout: pos_integer(),
  task_supervisor: GenServer.name(),
  max_concurrency: pos_integer(),
  task_store: %{adapter: module(), name: term()} | nil,
  tasks: %{required(String.t()) => task_runtime()},
  task_refs: %{required(reference()) => String.t()},
  in_flight: %{
    required(reference()) => %{
      ref: reference(),
      pid: pid(),
      request_id: String.t(),
      from: GenServer.from(),
      started_at: integer(),
      method: String.t(),
      base_frame: Backplane.McpProtocol.Server.Frame.t()
    }
  },
  request_queue: :queue.queue({map(), map(), GenServer.from()}),
  deferred_callbacks: :queue.queue({:cast | :info, term()})
}
```

# `task_runtime`

```elixir
@type task_runtime() :: %{
  worker_ref: reference() | nil,
  worker_pid: pid() | nil,
  ttl_timer: reference() | nil,
  waiters: [task_waiter()],
  request_id: String.t() | integer()
}
```

# `task_waiter`

```elixir
@type task_waiter() ::
  {from :: GenServer.from(), request_id :: String.t() | integer()}
```

# `auto_initialize`

```elixir
@spec auto_initialize(GenServer.server()) :: :ok | {:error, term()}
```

Auto-initializes a session without a client initialize handshake.

This is used when a client sends a non-initialize request to an expired or
unknown session. Instead of returning 404, the server can create a new session
and auto-initialize it so the request can be processed transparently.

Uses the server's latest supported protocol version and synthetic client info
(`%{"name" => "auto-recovered", "version" => "unknown"}`). Server implementations
should not rely on this identity for client-specific decisions.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `get_schema`

# `initialized?`

```elixir
@spec initialized?(GenServer.server()) :: boolean()
```

Returns whether the MCP initialization handshake has completed.

# `notify`

```elixir
@spec notify(GenServer.server(), map(), map(), timeout()) :: :ok
```

Processes an MCP notification before acknowledging the caller.

# `parse_options`

# `parse_options!`

# `protocol_version`

```elixir
@spec protocol_version(GenServer.server()) :: String.t() | nil
```

Returns the protocol version negotiated for the session.

# `start_link`

```elixir
@spec start_link(keyword()) :: GenServer.on_start()
```

Starts a Session process linked to the current process.

## Options

  * `:session_id` — unique session identifier (required)
  * `:server_module` — the MCP server module implementing `Backplane.McpProtocol.Server` (required)
  * `:name` — GenServer registration name (required)
  * `:transport` — transport configuration `[layer: module, name: name]` (required)
  * `:task_supervisor` — name of the `Task.Supervisor` for async work (required)
  * `:max_concurrency` — maximum concurrent request tasks per session (default: 1)
  * `:registry` — session registry module (default: `Backplane.McpProtocol.Server.Registry`)
  * `:session_idle_timeout` — idle timeout in ms before session expires (default: 30 min)
  * `:timeout` — request timeout in ms (default: 30s)

---

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