GenServer that manages the state for a single agent-client connection.

The Connection module is a core component in the ACPex OTP architecture, sitting between the transport layer and individual session processes. It is responsible for:

• Handling connection-level protocol messages (initialize, authenticate)
• Managing the lifecycle of session processes via a SessionSupervisor
• Routing messages to the appropriate session based on session_id
• Handling bidirectional JSON-RPC communication
• Managing pending requests and matching responses

Architecture

Each connection spawns its own supervision tree:

Connection.GenServer
├── SessionSupervisor
│   ├── Session.GenServer (session_id_1)
│   ├── Session.GenServer (session_id_2)
│   └── ...

Message Flow

1. Incoming messages arrive via {:message, json_rpc_message}
2. Connection-level messages are handled directly by calling the handler module
3. Session-level messages are forwarded to the appropriate session process
4. Responses are matched with pending requests via their id field

Examples

# Start an agent connection
{:ok, pid} = Connection.start_link(
  handler_module: MyAgent,
  handler_args: [],
  role: :agent,
  transport_pid: transport_pid
)

# Send a notification to the other party
Connection.send_notification(pid, "session/update", %{
  "session_id" => "abc123",
  "update" => %{"kind" => "message", "content" => "Hello"}
})

# Send a request and await response
response = Connection.send_request(pid, "fs/read_text_file", %{
  "path" => "/tmp/file.txt"
})