# `Agentic.Protocol.ACP.Session`

ACP session lifecycle management.

Manages the full ACP connection lifecycle:
1. `initialize` -- negotiate protocol version and capabilities
2. `authenticate` -- if agent requires authentication
3. `session/new` -- create a new conversation session
4. `session/prompt` -- send user messages, collect streaming updates
5. `session/cancel` -- cancel an ongoing prompt turn
6. Cleanup -- close connection gracefully

## Usage

    {:ok, session} = Agentic.Protocol.ACP.Session.connect(
      client: acp_client,
      workspace: "/path/to/project",
      permission_policy: :ask
    )

    {:ok, response, session} = Agentic.Protocol.ACP.Session.prompt(
      session,
      [%{"type" => "text", "text" => "Hello"}]
    )

    :ok = Agentic.Protocol.ACP.Session.cancel(session)
    :ok = Agentic.Protocol.ACP.Session.close(session)

# `session`

```elixir
@type session() :: %Agentic.Protocol.ACP.Session{
  agent_capabilities: map() | nil,
  agent_info: map() | nil,
  client: pid(),
  mcp_servers: [map()],
  permission_policy: atom(),
  prompt_accumulator: String.t(),
  protocol_version: pos_integer() | nil,
  session_id: String.t() | nil,
  updates: [map()],
  workspace: String.t()
}
```

# `can_load_session?`

```elixir
@spec can_load_session?(session()) :: boolean()
```

Check if the agent supports session loading.

# `cancel`

```elixir
@spec cancel(
  session(),
  keyword()
) :: :ok
```

Cancel the current prompt turn.

# `close`

```elixir
@spec close(
  session(),
  keyword()
) :: :ok
```

Close the session and stop the client.

# `connect`

```elixir
@spec connect(keyword()) :: {:ok, session()} | {:error, term()}
```

Connect to an ACP agent: initialize, authenticate (if needed), create session.

## Options

  - `:client` - ACP Client pid (required)
  - `:workspace` - Working directory for the session (required)
  - `:permission_policy` - `:ask`, `:allow_all`, or `:deny_all` (default `:ask`)
  - `:mcp_servers` - List of MCP server configs to forward (default `[]`)
  - `:client_info` - Override client info sent during initialize
  - `:client_capabilities` - Override client capabilities

# `load`

```elixir
@spec load(session(), String.t()) :: {:ok, session()} | {:error, term()}
```

Load an existing session by ID.

Only works if the agent advertised `loadSession: true` during initialize.

# `prompt`

```elixir
@spec prompt(session(), [Agentic.Protocol.ACP.Types.content_block()], keyword()) ::
  {:ok, map(), session()} | {:error, term()}
```

Send a prompt to the agent and collect the response.

Returns `{:ok, response, session}` where response contains:
- `:content` - accumulated text content
- `:tool_calls` - list of tool calls made during the turn
- `:stop_reason` - why the agent stopped
- `:updates` - all raw session/update notifications received

# `set_mode`

```elixir
@spec set_mode(session(), String.t()) :: :ok | {:error, term()}
```

Switch the agent operating mode.

# `supports_audio?`

```elixir
@spec supports_audio?(session()) :: boolean()
```

Check if the agent supports audio input.

# `supports_image?`

```elixir
@spec supports_image?(session()) :: boolean()
```

Check if the agent supports image input.

---

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